eslint-plugin-traceability 1.8.0 → 1.8.2

package/lib/tests/utils/ioTestHelpers.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFallbackTextBeforeHasStoryDetectsStoryTest = runFallbackTextBeforeHasStoryDetectsStoryTest;
+/**
+ * Shared IO helper tests for require-story-io behavior.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-TEST-UTILS-IO - Provide reusable helpers for IO-related edge case tests
+ */
+function runFallbackTextBeforeHasStoryDetectsStoryTest(storyAnnotationOrFallbackFn = "@story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md", maybeFallbackFn) {
+    const isFirstArgFn = typeof storyAnnotationOrFallbackFn === "function";
+    const storyAnnotation = isFirstArgFn
+        ? "@story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md"
+        : storyAnnotationOrFallbackFn;
+    const fallbackFn = isFirstArgFn
+        ? storyAnnotationOrFallbackFn
+        : maybeFallbackFn;
+    const pre = `/* ${storyAnnotation} */\n`;
+    const rest = "function y() {}";
+    const full = pre + rest;
+    const fakeSource = { getText: () => full };
+    const node = { range: [full.indexOf("function"), full.length] };
+    expect(fallbackFn(fakeSource, node)).toBe(true);
+}

package/lib/tests/utils/temp-dir-helpers.d.ts

@@ -0,0 +1,14 @@
+export interface TempDirHandle {
+    /** The absolute path to the created temporary directory. */
+    readonly dir: string;
+    /** Remove the directory recursively; safe to call multiple times. */
+    cleanup(): void;
+}
+/**
+ * Create a temporary directory under the OS temp root with a common prefix.
+ *
+ * This helper centralizes the mkdtemp + rmSync pattern that appears in
+ * multiple maintenance tests so those tests can focus on behavior instead
+ * of filesystem plumbing.
+ */
+export declare function createTempDir(prefix: string): TempDirHandle;

package/lib/tests/utils/temp-dir-helpers.js

@@ -0,0 +1,61 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTempDir = createTempDir;
+/**
+ * Shared temp directory helpers for maintenance tests.
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-TEMP-HELPERS - Provide reusable OS tempdir setup/cleanup utilities for tests
+ */
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+/**
+ * Create a temporary directory under the OS temp root with a common prefix.
+ *
+ * This helper centralizes the mkdtemp + rmSync pattern that appears in
+ * multiple maintenance tests so those tests can focus on behavior instead
+ * of filesystem plumbing.
+ */
+function createTempDir(prefix) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    return {
+        dir,
+        cleanup() {
+            // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
+            fs.rmSync(dir, { recursive: true, force: true });
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "description": "A customizable ESLint plugin that enforces traceability annotations in your code, ensuring each implementation is linked to its requirement or test case.",
   "main": "lib/src/index.js",
   "types": "lib/src/index.d.ts",
@@ -8,8 +8,8 @@
     "lib",
     "README.md",
     "LICENSE",
+    "SECURITY.md",
     "user-docs",
-    "docs",
     "CHANGELOG.md"
   ],
   "directories": {
@@ -20,7 +20,8 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "prepare": "husky install",
+    "prepare": "",
+    "postinstall": "husky",
     "type-check": "tsc --noEmit -p tsconfig.json",
     "check:traceability": "node scripts/traceability-check.js",
     "lint-plugin-check": "node scripts/lint-plugin-check.js",
@@ -67,8 +68,8 @@
     "@eslint/js": "^9.39.1",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^10.3.5",
-    "@semantic-release/npm": "^10.0.6",
+    "@semantic-release/github": "12.0.2",
+    "@semantic-release/npm": "13.1.2",
     "@types/eslint": "^9.6.1",
     "@types/jest": "^30.0.0",
     "@types/node": "^24.10.1",
@@ -80,9 +81,9 @@
     "husky": "^9.1.7",
     "jest": "^30.2.0",
     "jscpd": "^4.0.5",
-    "lint-staged": "^16.2.6",
+    "lint-staged": "^16.2.7",
     "prettier": "^3.6.2",
-    "semantic-release": "^21.1.2",
+    "semantic-release": "25.0.2",
     "ts-jest": "^29.4.5",
     "typescript": "^5.9.3",
     "secretlint": "11.2.5",

package/user-docs/api-reference.md

@@ -11,13 +11,15 @@ 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.
 
-In addition to the core `@story` and `@req` annotations, the plugin also understands `@implements` for code that fulfills requirements from multiple stories—for example:
-`@implements docs/stories/010.0-PAYMENTS.story.md#REQ-PAYMENTS-REFUND`.
-For a detailed explanation of `@implements` behavior and validation, see [`user-docs/migration-guide.md`](../user-docs/migration-guide.md) (section **3.1 Multi-story @implements annotations**) and the rule docs at [`docs/rules/valid-annotation-format.md`](../docs/rules/valid-annotation-format.md) and [`docs/rules/valid-req-reference.md`](../docs/rules/valid-req-reference.md).
+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-implements-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. Detailed behavior and migration guidance are documented in the project’s internal rule documentation, which is targeted at maintainers; typical end users can rely on the high-level guidance in this API reference and the [Migration Guide](migration-guide.md).
 
 ### traceability/require-story-annotation
 
-Description: Ensures every function declaration has a JSDoc comment with an `@story` annotation referencing the related user story. 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 currently fixed but structured for future configurability, and fixes are strictly limited to adding this placeholder annotation without altering the function body or changing any runtime behavior. Selective enabling of different auto-fix behaviors (such as applying fixes only to certain scopes or node types) is planned for a future version.
+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 currently fixed but structured for future configurability, and fixes are strictly limited to adding this placeholder annotation without altering the function body or changing any runtime behavior. Selective enabling of different auto-fix behaviors (such as applying fixes only to certain scopes or node types) is planned for a future version.
 
 Options:
 
@@ -39,7 +41,7 @@ function initAuth() {
 
 ### 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. Arrow functions (`ArrowFunctionExpression`) are not currently checked by this rule.
+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.
 
 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.
 
@@ -88,11 +90,11 @@ Options:
 This rule accepts an optional configuration object. The primary configuration shape is **nested**:
 
 - `story` (object, optional) – Configuration for `@story` values.
-  - `pattern` (string, optional) – A JavaScript regular expression **source** (without leading and trailing `/`) that all `@story` values must match. If provided, the rule validates each `@story` against this pattern in addition to its built‑in structural checks. Defaults to the value returned by `getDefaultStoryPattern()`, which is equivalent to `^docs/stories/.*\.story\.md$`, aligning with the standard `docs/stories/<name>.story.md` convention.
-  - `example` (string, optional) – A short example `@story` path shown in error messages when `story.pattern` is configured. Defaults to the value returned by `getDefaultStoryExample()`, `"docs/stories/001.0-EXAMPLE.story.md"`. This value is used **only** for guidance and does not affect validation.
+  - `pattern` (string, optional) – A JavaScript regular expression **source** (without leading and trailing `/`) that all `@story` values must match. If provided, the rule validates each `@story` against this pattern in addition to its built‑in structural checks. By default, the plugin uses a pattern equivalent to `^docs/stories/.*\.story\.md$`, which matches a typical project convention such as `docs/stories/<name>.story.md`; you can override this to match however your own project organizes story files.
+  - `example` (string, optional) – A short example `@story` path shown in error messages when `story.pattern` is configured. The built-in default example is `"docs/stories/001.0-EXAMPLE.story.md"`, intended as a generic illustration of a project story file, and does not refer to this plugin’s internal documentation.
 - `req` (object, optional) – Configuration for `@req` values.
   - `pattern` (string, optional) – A JavaScript regular expression **source** (without leading and trailing `/`) that all `@req` values must match. If provided, the rule validates each `@req` identifier against this pattern. Defaults to the value returned by `getDefaultReqPattern()`, which is equivalent to `^REQ-[A-Z0-9_-]+$`, matching IDs such as `REQ-USER-AUTH` or `REQ-1234`.
-  - `example` (string, optional) – A short example requirement ID shown in error messages when `req.pattern` is configured. Defaults to the value returned by `getDefaultReqExample()`, `"REQ-USER-AUTH"`. This is purely informational and does not participate in matching.
+  - `example` (string, optional) – A short example requirement ID shown in error messages when `req.pattern` is configured. Defaults to the value returned by `getDefaultReqExample()`, `"REQ-USER-AUTH"`. This value is used **only** for guidance and does not affect validation.
 
 For backward compatibility, the rule also supports **flat shorthand** fields that map directly to the nested properties:
 
@@ -112,13 +114,10 @@ Behavior notes:
 The `valid-annotation-format` rule is intentionally **backward compatible** with existing code that only uses `@story` and `@req`. You can:
 
 - Continue using `@story` + `@req` for single-story functions and modules.
-- Introduce `@implements` incrementally for integration code that implements requirements from multiple stories.
+- Introduce `@supports` incrementally for integration code that implements requirements from multiple stories.
 - Mix both styles in the same comment block when needed; the rule validates the format of each annotation independently.
 
-Deep requirement checking for both `@req` and `@implements` is handled by `traceability/valid-req-reference`. For step-by-step guidance on when and how to migrate, see:
-
-- **Migration guide:** [`user-docs/migration-guide.md`](../user-docs/migration-guide.md) (section **3.1 Multi-story `@implements` annotations**)
-- **Rule docs:** [`docs/rules/valid-annotation-format.md`](../docs/rules/valid-annotation-format.md), [`docs/rules/valid-req-reference.md`](../docs/rules/valid-req-reference.md)
+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:
@@ -196,9 +195,12 @@ The plugin provides two built-in presets for easy configuration:
 
 ### recommended
 
-Enables the core traceability rules with severities tuned for common usage (most at `error`, with
-`traceability/valid-annotation-format` at `warn` to reduce noise):
-This `warn` level for `traceability/valid-annotation-format` is intentional to keep early adoption noise low, but you can safely raise it to `error` in projects that want strict enforcement of annotation formatting.
+Enables the **six core traceability rules** with severities tuned for common usage (most at `error`, with
+`traceability/valid-annotation-format` at `warn` to reduce noise). This `warn` level for `traceability/valid-annotation-format` is intentional to keep early adoption noise low, but you can safely raise it to `error` in projects that want strict enforcement of annotation formatting.
+
+The `prefer-implements-annotation` migration rule is **not included** in this (or any) preset and remains disabled by default. If you want to encourage or enforce multi-story `@supports` annotations, you must enable `traceability/prefer-implements-annotation` explicitly in your ESLint configuration and choose an appropriate severity (for example, `"warn"` during migration or `"error"` once fully adopted).
+
+Core rules enabled by the `recommended` preset:
 
 - `traceability/require-story-annotation`: `error`
 - `traceability/require-req-annotation`: `error`
@@ -218,7 +220,8 @@ export default [js.configs.recommended, traceability.configs.recommended];
 
 ### strict
 
-Currently mirrors the **recommended** preset, reserved for future stricter policies.
+Currently mirrors the **recommended** preset, reserved for future stricter policies. As with the `recommended` preset, the `traceability/prefer-implements-annotation` rule is **not** enabled here by default and must be configured manually if desired.
+
 Usage:
 
 ```javascript
@@ -234,16 +237,30 @@ The plugin exposes a small maintenance API and a companion CLI, `traceability-ma
 
 ### Programmatic Maintenance API
 
-All functions are exported from the plugin’s maintenance module:
+The maintenance functions are available via the plugin’s `maintenance` export. You can either import the named `maintenance` export directly and destructure the functions you need, or import the default plugin export and access the same functions from `traceability.maintenance`:
 
 ```ts
-import {
+// Option 1: Named `maintenance` export
+import { maintenance } from "eslint-plugin-traceability";
+
+const {
   detectStaleAnnotations,
   updateAnnotationReferences,
   batchUpdateAnnotations,
   verifyAnnotations,
   generateMaintenanceReport,
-} from "eslint-plugin-traceability/maintenance";
+} = maintenance;
+
+// Option 2: Default plugin export
+import traceability from "eslint-plugin-traceability";
+
+const {
+  detectStaleAnnotations: detectStaleAnnotations2,
+  updateAnnotationReferences: updateAnnotationReferences2,
+  batchUpdateAnnotations: batchUpdateAnnotations2,
+  verifyAnnotations: verifyAnnotations2,
+  generateMaintenanceReport: generateMaintenanceReport2,
+} = traceability.maintenance;
 ```
 
 The current maintenance API operates on a **single workspace root** and scans all files beneath that directory. It does not yet accept include/exclude globs or explicit story/requirement lists.

package/user-docs/eslint-9-setup-guide.md

@@ -28,6 +28,9 @@ npm install --save-dev eslint@^9.39.1
 # Recommended configurations
 npm install --save-dev @eslint/js@^9.39.1
 
+# Traceability plugin
+npm install --save-dev eslint-plugin-traceability@^1.0.0
+
 # For TypeScript projects
 npm install --save-dev @typescript-eslint/parser@^8.0.0
 npm install --save-dev @typescript-eslint/utils@^8.0.0
@@ -67,13 +70,48 @@ export default [
 
 ### 4. Enable Traceability Plugin
 
-To integrate the traceability plugin, update your `eslint.config.js` to include its recommended configuration:
+To integrate the traceability plugin with its **recommended** preset, update your `eslint.config.js`:
+
+```javascript
+import js from "@eslint/js";
+import traceability from "eslint-plugin-traceability";
+
+export default [
+  js.configs.recommended,
+  {
+    plugins: {
+      traceability,
+    },
+  },
+  ...traceability.configs.recommended,
+];
+```
+
+To use the **strict** preset instead:
 
 ```javascript
 import js from "@eslint/js";
 import traceability from "eslint-plugin-traceability";
 
-export default [js.configs.recommended, traceability.configs.recommended];
+export default [
+  js.configs.recommended,
+  {
+    plugins: {
+      traceability,
+    },
+  },
+  ...traceability.configs.strict,
+];
+```
+
+Note: The `traceability.configs.recommended` and `traceability.configs.strict` presets define rule severities only. They expect the plugin to be registered in a preceding flat-config object via:
+
+```javascript
+{
+  plugins: {
+    traceability,
+  },
+}
 ```
 
 ## Configuration File Format
@@ -137,9 +175,16 @@ Both forms are supported by ESLint 9 as long as the file extension and `package.
 ```javascript
 // eslint.config.js
 import js from "@eslint/js";
+import traceability from "eslint-plugin-traceability";
 
 export default [
   js.configs.recommended,
+  {
+    plugins: {
+      traceability,
+    },
+  },
+  ...traceability.configs.recommended,
   {
     files: ["**/*.js", "**/*.mjs"],
     languageOptions: {
@@ -163,9 +208,16 @@ export default [
 // eslint.config.js
 import js from "@eslint/js";
 import typescriptParser from "@typescript-eslint/parser";
+import traceability from "eslint-plugin-traceability";
 
 export default [
   js.configs.recommended,
+  {
+    plugins: {
+      traceability,
+    },
+  },
+  ...traceability.configs.recommended,
   {
     files: ["**/*.ts", "**/*.tsx"],
     languageOptions: {
@@ -197,9 +249,16 @@ export default [
 // eslint.config.js
 import js from "@eslint/js";
 import typescriptParser from "@typescript-eslint/parser";
+import traceability from "eslint-plugin-traceability";
 
 export default [
   js.configs.recommended,
+  {
+    plugins: {
+      traceability,
+    },
+  },
+  ...traceability.configs.recommended,
   {
     files: ["**/*.{js,jsx,ts,tsx}"],
     languageOptions: {
@@ -282,9 +341,16 @@ export default [
 // eslint.config.js
 import js from "@eslint/js";
 import typescriptParser from "@typescript-eslint/parser";
+import traceability from "eslint-plugin-traceability";
 
 export default [
   js.configs.recommended,
+  {
+    plugins: {
+      traceability,
+    },
+  },
+  ...traceability.configs.recommended,
   {
     // Lint all packages in a monorepo/workspace
     files: ["packages/*/src/**/*.{js,ts,tsx}"],
@@ -479,9 +545,16 @@ Solution: Use combined file patterns or separate override blocks, and import the
 // eslint.config.js
 import js from "@eslint/js";
 import typescriptParser from "@typescript-eslint/parser";
+import traceability from "eslint-plugin-traceability";
 
 export default [
   js.configs.recommended,
+  {
+    plugins: {
+      traceability,
+    },
+  },
+  ...traceability.configs.recommended,
   {
     files: ["**/*.{js,jsx,ts,tsx}"],
     languageOptions: {
@@ -512,6 +585,7 @@ Here's a complete working configuration for a TypeScript ESLint plugin project:
 // eslint.config.js
 import js from "@eslint/js";
 import typescriptParser from "@typescript-eslint/parser";
+import traceability from "eslint-plugin-traceability";
 
 // Conditional plugin loading (for plugin development)
 let plugin;
@@ -524,6 +598,15 @@ try {
 
 export default [
   js.configs.recommended,
+  {
+    // Register the traceability plugin for subsequent presets/rules
+    plugins: {
+      traceability,
+      ...(plugin.rules ? { traceabilityDev: plugin } : {}),
+    },
+  },
+  // Apply the recommended preset for the published plugin
+  ...traceability.configs.recommended,
   {
     // Node.js config files (CommonJS)
     files: ["*.config.js", "*.config.mjs", "jest.config.js"],
@@ -554,7 +637,7 @@ export default [
       },
     },
     plugins: {
-      ...(plugin.rules ? { traceability: plugin } : {}),
+      ...(plugin.rules ? { traceabilityDev: plugin } : {}),
     },
     rules: {
       "@typescript-eslint/no-unused-vars": "error",
@@ -568,7 +651,7 @@ export default [
       sourceType: "module",
     },
     plugins: {
-      ...(plugin.rules ? { traceability: plugin } : {}),
+      ...(plugin.rules ? { traceabilityDev: plugin } : {}),
     },
   },
   {
@@ -621,6 +704,7 @@ export default [
     "@typescript-eslint/parser": "^8.46.4",
     "@typescript-eslint/utils": "^8.46.4",
     "eslint": "^9.39.1",
+    "eslint-plugin-traceability": "^1.0.0",
     "typescript": "^5.9.3"
   }
 }
@@ -635,5 +719,4 @@ export default [
 5. **Use file patterns** instead of CLI `--ext` flags
 6. **Structure as array of objects**, each targeting specific file types
 7. **Use `ignores`** instead of `.eslintignore` files
-
-This setup provides a solid foundation for ESLint 9 that works reliably across different project types and environments.
+8. **Register plugins explicitly** in flat config before spreading their presets

package/user-docs/migration-guide.md

@@ -37,25 +37,44 @@ export default [traceability.configs.recommended];
 - `valid-req-reference` rejects path traversal (`../`) and absolute paths (`/etc/passwd`).
 - `valid-annotation-format` enforces correct JSDoc traceability annotation syntax (`@story` and `@req` tags).
 
-Review and update your existing annotations accordingly:
+The following diff shows a typical migration in **your own project**, where `docs/stories/001.0-DEV-PLUGIN-SETUP.story.md` is an example of a story file path from your documentation tree:
 
 ```diff
 - /** @story docs/stories/001.0-DEV-PLUGIN-SETUP.md */
 + /** @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md */
 ```
 
-### 3.1 Multi-story `@implements` annotations
+### 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:
+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:
 
 ```js
 /**
- * @implements docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md REQ-IMPLEMENTS-PARSE REQ-IMPLEMENTS-VALIDATE
+ * @supports docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md REQ-IMPLEMENTS-PARSE REQ-IMPLEMENTS-VALIDATE
  */
 function integrate() {}
 ```
 
-You **do not** need to change existing, single-story annotations that already use `@story` and `@req`. Migration to `@implements` is only recommended when a function or module genuinely implements requirements from more than one story file.
+You **do not** need to change existing, single-story annotations that already use `@story` and `@req`. Migration to `@supports` is only recommended when a function or module genuinely implements requirements from more than one story file.
+
+#### Optional `prefer-implements-annotation` migration rule
+
+For teams that want to gradually migrate from `@story` + `@req` to `@supports`, the plugin provides an optional rule: `traceability/prefer-implements-annotation`.
+
+- This rule is **disabled by default** and is **not** included in any built-in presets.
+- You can enable it with any standard ESLint severity (`"off"`, `"warn"`, or `"error"`) in your config, for example:
+
+  ```js
+  // excerpt from eslint.config.js
+  {
+    rules: {
+      "traceability/prefer-implements-annotation": "warn",
+    },
+  }
+  ```
+
+- When enabled, it offers **conservative auto-fixes** that rewrite eligible `@story` + `@req` combinations into equivalent `@supports` lines, without attempting risky or ambiguous transformations.
+- Detailed behavior, limitations, and examples are documented in the project’s internal rule documentation, which is primarily intended for maintainers; most users can rely on this guide and the API reference for day-to-day usage.
 
 #### When to keep `@story` + `@req`
 
@@ -65,7 +84,7 @@ Keep your current annotations if:
 - All relevant requirements live in that story file.
 - You do not need to distinguish which story a particular requirement ID comes from.
 
-Example (no migration required):
+Example (no migration required). Here, `docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md` is an illustrative path representing a typical story file location in **your** documentation structure:
 
 ```js
 /**
@@ -77,15 +96,15 @@ export function initAuth() {
 }
 ```
 
-#### When to introduce `@implements`
+#### When to introduce `@supports`
 
-Adopt `@implements` for **multi-story integration** code, especially when:
+Adopt `@supports` for **multi-story integration** code, especially when:
 
 - The function combines behavior governed by **multiple** stories.
 - Requirement IDs are reused across stories (for example, `REQ-SHARED-ID` appears in more than one story file).
 - You want deep validation (via `valid-req-reference`) to know **which story file** each requirement came from.
 
-Before (single-story annotations trying to describe multi-story behavior):
+Before (single-story annotations trying to describe multi-story behavior). The story path shown here is an example of how you might name and organize a story file in your own project:
 
 ```js
 /**
@@ -99,7 +118,7 @@ export async function applyFilters(rows, options) {
 }
 ```
 
-After (multi-story `@implements`), aligned with Story 010.2:
+After (multi-story `@supports`), using illustrative story paths that represent typical files in your project’s documentation tree (they are examples, not files provided by this plugin):
 
 ```js
 /**
@@ -108,8 +127,8 @@ After (multi-story `@implements`), aligned with Story 010.2:
  * @req REQ-AGE-THRESHOLD
  * @req REQ-OUTPUT
  *
- * @implements docs/stories/003.0-DEV-IDENTIFY-OUTDATED.story.md REQ-AGE-THRESHOLD REQ-OUTPUT
- * @implements docs/stories/004.0-DEV-FILTER-VULNERABLE-VERSIONS.story.md REQ-AUDIT-CHECK REQ-SAFE-ONLY
+ * @supports docs/stories/003.0-DEV-IDENTIFY-OUTDATED.story.md REQ-AGE-THRESHOLD REQ-OUTPUT
+ * @supports docs/stories/004.0-DEV-FILTER-VULNERABLE-VERSIONS.story.md REQ-AUDIT-CHECK REQ-SAFE-ONLY
  */
 export async function applyFilters(rows, options) {
   // combined behavior
@@ -118,22 +137,19 @@ export async function applyFilters(rows, options) {
 
 In the "after" example:
 
-- `valid-annotation-format` ensures the `@implements` lines use a valid story path and requirement ID format.
-- `valid-req-reference` validates that each requirement listed after `@implements` exists in the corresponding story file.
+- `valid-annotation-format` ensures the `@supports` lines use a valid story path and requirement ID format.
+- `valid-req-reference` validates that each requirement listed after `@supports` exists in the corresponding story file.
 
 #### Mixed usage during migration
 
-You can introduce `@implements` gradually without breaking existing code:
+You can introduce `@supports` gradually without breaking existing code:
 
 1. Leave existing `@story` and `@req` annotations in place.
-2. Add `@implements` lines that group requirements by story file.
+2. Add `@supports` lines that group requirements by story file.
 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 `@implements` for multi-story integration functions while keeping `@story` + `@req` for simple, single-story code.
-
-For detailed semantics and edge cases (path validation, scoped requirement IDs, and multi-story fixtures), see:
+4. Optionally, once you are comfortable, standardize on using `@supports` for multi-story integration functions while keeping `@story` + `@req` for simple, single-story code.
 
-- Rule docs: [`docs/rules/valid-annotation-format.md`](../docs/rules/valid-annotation-format.md), [`docs/rules/valid-req-reference.md`](../docs/rules/valid-req-reference.md)
-- Story: [`docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md`](../docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md)
+Detailed semantics and edge cases (path validation, scoped requirement IDs, and multi-story fixtures) are ultimately governed by your own stories and requirements. For typical migrations, this guide together with the plugin’s API reference is sufficient.
 
 ## 4. Test and Validate