eslint-plugin-traceability 1.8.0 → 1.8.1

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-# [1.8.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.7.1...v1.8.0) (2025-12-03)
+## [1.8.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.8.0...v1.8.1) (2025-12-04)
 
 
-### Features
+### Bug Fixes
 
-* accept [@implements](https://github.com/implements) annotations in require rules ([bdf0994](https://github.com/voder-ai/eslint-plugin-traceability/commit/bdf0994f0d0e16bd751fbd89c08c67bddee52c16))
+* disable prefer-implements-annotation in default presets ([89c62e9](https://github.com/voder-ai/eslint-plugin-traceability/commit/89c62e907be95030f89e6a3ab6df24a4ba32ab62))
 
 # Changelog
 

package/README.md

@@ -35,22 +35,30 @@ This example shows the recommended starting point using the plugin's recommended
 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.recommended,
+];
 ```
 
 ### Available Rules
 
-- `traceability/require-story-annotation` Enforces presence of `@story` annotations. ([Documentation](docs/rules/require-story-annotation.md))
-- `traceability/require-req-annotation` Enforces presence of `@req` annotations. ([Documentation](docs/rules/require-req-annotation.md))
-- `traceability/require-branch-annotation` Enforces presence of branch annotations. ([Documentation](docs/rules/require-branch-annotation.md))
-- `traceability/valid-annotation-format` Enforces correct format of traceability annotations. ([Documentation](docs/rules/valid-annotation-format.md))
-- `traceability/valid-story-reference` Validates that `@story` references point to existing story files. ([Documentation](docs/rules/valid-story-reference.md))
-- `traceability/valid-req-reference` Validates that `@req` references point to existing requirement IDs. ([Documentation](docs/rules/valid-req-reference.md))
-- `traceability/prefer-implements-annotation` Recommends migration from legacy `@story`/`@req` annotations to `@implements` (disabled by default). ([Documentation](docs/rules/prefer-implements-annotation.md))
+- `traceability/require-story-annotation` Enforces presence of `@story` annotations. (See the rule documentation in the plugin's user guide.)
+- `traceability/require-req-annotation` Enforces presence of `@req` annotations. (See the rule documentation in the plugin's user guide.)
+- `traceability/require-branch-annotation` Enforces presence of branch annotations. (See the rule documentation in the plugin's user guide.)
+- `traceability/valid-annotation-format` Enforces correct format of traceability annotations. (See the rule documentation in the plugin's user guide.)
+- `traceability/valid-story-reference` Validates that `@story` references point to existing story files. (See the rule documentation in the plugin's user guide.)
+- `traceability/valid-req-reference` Validates that `@req` references point to existing requirement IDs. (See the rule documentation in the plugin's user guide.)
+- `traceability/prefer-implements-annotation` Recommends migration from legacy `@story`/`@req` annotations to `@implements` (opt-in; disabled by default in the presets and must be explicitly enabled). (See the rule documentation in the plugin's user guide.)
 
-Configuration options: For detailed per-rule options (such as scopes, branch types, and story directory settings), see the individual rule docs in [`docs/rules/`](docs/rules) and the consolidated [API Reference](user-docs/api-reference.md).
+Configuration options: For detailed per-rule options (such as scopes, branch types, and story directory settings), see the individual rule docs in the plugin's user guide and the consolidated [API Reference](user-docs/api-reference.md).
 
-For development and contribution guidelines, see the [ESLint Plugin Development Guide](docs/eslint-plugin-development-guide.md).
+For development and contribution guidelines, see the contribution guide in the repository.
 
 ## Quick Start
 
@@ -61,8 +69,12 @@ For development and contribution guidelines, see the [ESLint Plugin Development
 import traceability from "eslint-plugin-traceability";
 
 export default [
-  // Load the traceability plugin's recommended rule set
-  traceability.configs.recommended,
+  {
+    plugins: {
+      traceability,
+    },
+  },
+  ...traceability.configs.recommended,
 ];
 ```
 
@@ -183,6 +195,8 @@ These tests verify end-to-end behavior of the plugin via the ESLint CLI.
 
 ## Security and Dependency Health
 
+For the canonical, user-facing security policy (including how to report vulnerabilities), see [SECURITY.md](SECURITY.md). The additional files under `docs/` referenced below provide deeper background and implementation details for interested readers.
+
 ### What end users can expect from production dependencies
 
 - The published `eslint-plugin-traceability` package is intended to ship **only with production dependencies that have no known high‑severity vulnerabilities** at release time.
@@ -217,29 +231,14 @@ These tests verify end-to-end behavior of the plugin via the ESLint CLI.
   - The issue is confined to the CI environment that prepares and publishes releases.
   - It **cannot impact** the runtime behavior or dependency graph of the `eslint-plugin-traceability` package you install or use in your own projects.
 
-### Optional deeper background
-
-For readers who want more context on the dependency and security model (not required to use the plugin):
-
-- Dependency health overview: [docs/dependency-health.md](docs/dependency-health.md)
-- Detailed incident note about the semantic‑release/npm toolchain risk:  
-  [docs/security-incidents/SECURITY-INCIDENT-2025-11-18-semantic-release-bundled-npm.known-error.md](docs/security-incidents/SECURITY-INCIDENT-2025-11-18-semantic-release-bundled-npm.known-error.md)
-
-These documents are informational and describe internal processes and known toolchain limitations; they do not change the guarantees described above for end users.
-
 ## Documentation Links
 
 - ESLint v9 Setup Guide: [user-docs/eslint-9-setup-guide.md](user-docs/eslint-9-setup-guide.md)
-- Plugin Development Guide: [docs/eslint-plugin-development-guide.md](docs/eslint-plugin-development-guide.md)
 - API Reference: [user-docs/api-reference.md](user-docs/api-reference.md)
 - Examples: [user-docs/examples.md](user-docs/examples.md)
 - Migration Guide: [user-docs/migration-guide.md](user-docs/migration-guide.md)
 - Full README: <https://github.com/voder-ai/eslint-plugin-traceability#readme>
-- Rule: require-story-annotation: [docs/rules/require-story-annotation.md](docs/rules/require-story-annotation.md)
-- Rule: require-req-annotation: [docs/rules/require-req-annotation.md](docs/rules/require-req-annotation.md)
-- Rule: require-branch-annotation: [docs/rules/require-branch-annotation.md](docs/rules/require-branch-annotation.md)
 - Contribution guide: <https://github.com/voder-ai/eslint-plugin-traceability/blob/main/CONTRIBUTING.md>
 - Issue tracker: <https://github.com/voder-ai/eslint-plugin-traceability/issues>
-- Configuration Presets: [docs/config-presets.md](docs/config-presets.md)
 - Changelog: [CHANGELOG.md](CHANGELOG.md)
 - Versioning and Releases: This project uses semantic-release for automated versioning. The authoritative list of published versions and release notes is on GitHub Releases: <https://github.com/voder-ai/eslint-plugin-traceability/releases>

package/SECURITY.md

@@ -0,0 +1,132 @@
+# Security Policy
+
+This document describes how security is handled for `eslint-plugin-traceability`, including how to report vulnerabilities, what guarantees apply to production dependencies, and how we manage known risks in our dev-only release tooling.
+
+> This file is **user-facing** documentation. Internal implementation details and deeper discussion live in the project’s internal documentation and decision records.
+
+## Reporting a Vulnerability
+
+If you believe you have found a security vulnerability in this project:
+
+1. **Do not open a public GitHub issue.**
+2. Instead, open a private security advisory via the GitHub Security tab for this repository:
+   - Navigate to: `Security` → `Advisories` → `Report a vulnerability`.
+3. Provide as much detail as you can (steps to reproduce, impact, affected environments). A maintainer will review and coordinate a fix and disclosure timeline with you.
+
+If you cannot use GitHub Security Advisories, you may alternatively open a **minimal** issue that does not disclose details and ask for a private contact channel.
+
+## Supported Versions
+
+This project uses [semantic-release](https://github.com/semantic-release/semantic-release) for automated versioning and publishing.
+
+- The **latest published version** on npm and GitHub Releases is considered supported.
+- Older versions are not actively maintained; security fixes are applied to the current release line and then published automatically.
+- To benefit from security fixes, users should stay reasonably up-to-date with the latest versions of `eslint-plugin-traceability`.
+
+Authoritative release information is available on GitHub Releases:
+
+- <https://github.com/voder-ai/eslint-plugin-traceability/releases>
+
+## Production Dependency Guarantees
+
+The `eslint-plugin-traceability` package has **no runtime dependencies**; it ships only its compiled plugin and CLI code plus documentation. Nevertheless, we treat any future production dependencies with care and enforce the following guarantees at release time:
+
+- Before a release is published, CI runs:
+  - `npm audit --omit=dev --audit-level=high`
+- A release is allowed to proceed only when:
+  - There are **no known high-severity vulnerabilities** reported in the **production (runtime) dependency tree**.
+
+In other words:
+
+- The published npm package is intended to ship **without known high‑severity vulnerabilities in its production dependencies** at the moment it is released.
+- Dev-only tooling and CI infrastructure are kept separate from what you install via `npm install eslint-plugin-traceability`.
+
+For more detail on how these checks are wired into CI, see the internal dependency health and security documentation for this project.
+
+## Dependency Maturity and `dry-aged-deps`
+
+In addition to `npm audit`, we use [`dry-aged-deps`](https://github.com/voder-ai/dry-aged-deps) to guide dependency upgrades for both production and development dependencies.
+
+Current high-level policy:
+
+- **Minimum age:** new versions are generally required to be **at least 7 days old** before adoption.
+- **No known vulnerabilities:** versions with _any_ known vulnerability (even low severity) are not considered "safe" upgrade candidates.
+
+`dry-aged-deps` is advisory only:
+
+- It does **not** modify `package.json` or install anything automatically.
+- It produces machine-readable reports that are stored as CI artifacts and referenced in internal security/incident documentation.
+
+When `dry-aged-deps` reports that there are **no safe upgrades available** under these thresholds, we may temporarily accept residual risk in dev-only tooling while keeping production dependencies clean and fully audited.
+
+For maintainers, the full process is described in the project’s internal dependency health and security guidelines.
+
+## Dev-Only Release Tooling Risk (semantic-release / npm / glob / brace-expansion)
+
+There is a known, documented risk in the **dev-only release toolchain** used by this project. It does **not** affect the runtime behavior of the published ESLint plugin or CLI, but it is relevant to how releases are built in CI.
+
+### What is affected?
+
+- The dev dependency `@semantic-release/npm@10.0.6` bundles `npm@9.5.0`, which in turn includes vulnerable versions of `glob` and `brace-expansion`.
+- The relevant advisories are:
+  - `glob` CLI command injection: [GHSA-5j98-mcp5-4vw2](https://github.com/advisories/GHSA-5j98-mcp5-4vw2)
+  - `brace-expansion` ReDoS: [GHSA-v6h2-p8h4-qcjw](https://github.com/advisories/GHSA-v6h2-p8h4-qcjw)
+- These vulnerable packages exist **only inside the npm binary bundled within `@semantic-release/npm`** and are used solely during automated publishing from CI.
+
+### What is _not_ affected?
+
+- The published `eslint-plugin-traceability` package has **no runtime dependencies** on this bundled npm or its `glob`/`brace-expansion` copies.
+- End-user projects that install and run `eslint-plugin-traceability` or `traceability-maint` **do not execute** this bundled tooling.
+- `npm audit --omit=dev --audit-level=high` continues to report **0 high‑severity vulnerabilities** for the production dependency tree at release time.
+
+### Why is this risk currently accepted?
+
+Under our `dry-aged-deps` policy (7‑day minimum age, no known vulnerabilities):
+
+- There is currently **no recommended, dry‑aged‑safe upgrade path** for the semantic-release/npm toolchain that would fully eliminate these bundled vulnerabilities.
+- We therefore treat this as a **known error in dev-only tooling** rather than a production risk.
+
+This acceptance is documented in detail in the project’s internal security incident records and architectural decision records.
+
+### Compensating Controls
+
+To keep this dev-only risk tightly contained, we apply several compensating controls:
+
+1. **Environment Isolation**
+   - The vulnerable tooling is used **only** in the GitHub Actions CI workflow (`.github/workflows/ci-cd.yml`).
+   - It runs in a single, controlled job that executes on pushes to the `main` branch, not for pull requests.
+   - The job runs on GitHub-hosted runners and does not have access to internal infrastructure.
+
+2. **Least-Privilege Permissions for Release**
+   - Workflow-level permissions default to `contents: read`.
+   - Elevated permissions (`contents: write`, `issues: write`, `pull-requests: write`, `id-token: write`) are scoped to the release job/step that runs semantic-release and are not used for general CI tasks.
+
+3. **Strict Input Handling**
+   - The CI configuration and project scripts **never invoke the `glob` CLI** with the dangerous `-c/--cmd` flags.
+   - The semantic-release/npm toolchain does **not** receive untrusted user input for glob patterns or environment variables.
+   - Release jobs operate only on the repository contents of this project plus standard CI-provided environment variables.
+
+4. **Audit and Monitoring**
+   - Dev-only vulnerabilities are tracked via `npm run audit:dev-high`, which writes a machine-readable report to `ci/npm-audit.json` for each CI run.
+   - `dry-aged-deps` reports (`ci/dry-aged-deps.json`) are stored as CI artifacts to document when no safe upgrade path exists under the configured thresholds.
+   - A nightly `dependency-health` workflow re-runs dev-dependency audits to keep this risk under continuous review.
+
+5. **Guarded semantic-release Invocation (CI-Only)**
+   - semantic-release is invoked **only from CI**, and guarded to ensure it runs under the intended safe context (GitHub Actions, push to `main`, CI environment).
+   - Local developers are not expected to run semantic-release directly; publishing is handled automatically by CI after all quality and security checks pass.
+
+### Upgrade Plan
+
+We intend to migrate away from the affected semantic-release/npm toolchain as soon as a safe, dry‑aged‑deps–approved upgrade path is available:
+
+1. Continue monitoring `dry-aged-deps` output for `@semantic-release/npm`, `semantic-release`, and related packages.
+2. When a newer, vulnerability-free version remains stable for at least 7 days and passes our audit checks, update the dev dependencies accordingly.
+3. After migration, convert the existing known-error record into a resolved incident that documents the fix and new baseline.
+
+Until then, the risk remains **limited to CI release automation** and does not change the guarantees we provide for production dependencies or end-user environments.
+
+---
+
+## Attribution
+
+Created autonomously by [voder.ai](https://voder.ai).

package/lib/src/index.d.ts

@@ -17,6 +17,11 @@ import { detectStaleAnnotations, updateAnnotationReferences, batchUpdateAnnotati
 declare const RULE_NAMES: readonly ["require-story-annotation", "require-req-annotation", "require-branch-annotation", "valid-annotation-format", "valid-story-reference", "valid-req-reference", "prefer-implements-annotation"];
 type RuleName = (typeof RULE_NAMES)[number];
 declare const rules: Record<RuleName, Rule.RuleModule>;
+declare const plugin: {
+    rules: typeof rules;
+    configs?: unknown;
+    maintenance?: unknown;
+};
 /**
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @req REQ-ERROR-SEVERITY - Map rule types to appropriate ESLint severity levels (errors vs warnings)
@@ -25,17 +30,11 @@ declare const rules: Record<RuleName, Rule.RuleModule>;
  */
 declare const configs: {
     recommended: {
-        plugins: {
-            traceability: {};
-        };
         rules: {
             [x: string]: "error" | "warn";
         };
     }[];
     strict: {
-        plugins: {
-            traceability: {};
-        };
         rules: {
             [x: string]: "error" | "warn";
         };
@@ -53,32 +52,4 @@ declare const maintenance: {
     generateMaintenanceReport: typeof generateMaintenanceReport;
 };
 export { rules, configs, maintenance };
-declare const _default: {
-    rules: Record<"require-story-annotation" | "require-req-annotation" | "require-branch-annotation" | "valid-annotation-format" | "valid-story-reference" | "valid-req-reference" | "prefer-implements-annotation", Rule.RuleModule>;
-    configs: {
-        recommended: {
-            plugins: {
-                traceability: {};
-            };
-            rules: {
-                [x: string]: "error" | "warn";
-            };
-        }[];
-        strict: {
-            plugins: {
-                traceability: {};
-            };
-            rules: {
-                [x: string]: "error" | "warn";
-            };
-        }[];
-    };
-    maintenance: {
-        detectStaleAnnotations: typeof detectStaleAnnotations;
-        updateAnnotationReferences: typeof updateAnnotationReferences;
-        batchUpdateAnnotations: typeof batchUpdateAnnotations;
-        verifyAnnotations: typeof verifyAnnotations;
-        generateMaintenanceReport: typeof generateMaintenanceReport;
-    };
-};
-export default _default;
+export default plugin;

package/lib/src/index.js

@@ -73,6 +73,9 @@ RULE_NAMES.forEach(
         };
     }
 });
+const plugin = {
+    rules,
+};
 /**
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @req REQ-ERROR-SEVERITY - Map rule types to appropriate ESLint severity levels (errors vs warnings)
@@ -86,18 +89,16 @@ const TRACEABILITY_RULE_SEVERITIES = {
     "traceability/valid-annotation-format": "warn",
     "traceability/valid-story-reference": "error",
     "traceability/valid-req-reference": "error",
-    "traceability/prefer-implements-annotation": "warn",
 };
 /**
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @req REQ-PLUGIN-STRUCTURE - Provide foundational plugin export and registration
  * @req REQ-ERROR-SEVERITY - Map rule types to appropriate ESLint severity levels (errors vs warnings)
+ * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
+ * @req REQ-CONFIG-PRESETS - Provide flat-config presets that self-register the plugin and core rules
  */
 function createTraceabilityFlatConfig() {
     return {
-        plugins: {
-            traceability: {},
-        },
         rules: {
             ...TRACEABILITY_RULE_SEVERITIES,
         },
@@ -114,6 +115,7 @@ const configs = {
     strict: [createTraceabilityFlatConfig()],
 };
 exports.configs = configs;
+plugin.configs = configs;
 /**
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINTENANCE-API-EXPORT - Expose maintenance utilities alongside core plugin exports
@@ -126,4 +128,5 @@ const maintenance = {
     generateMaintenanceReport: maintenance_1.generateMaintenanceReport,
 };
 exports.maintenance = maintenance;
-exports.default = { rules, configs, maintenance };
+plugin.maintenance = maintenance;
+exports.default = plugin;

package/lib/tests/config/flat-config-presets-integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/tests/config/flat-config-presets-integration.test.js

@@ -0,0 +1,75 @@
+"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 });
+/**
+ * Tests for: docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
+ * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
+ * @req REQ-CONFIG-PRESETS - Validate flat-config presets register traceability plugin and rules
+ * @req REQ-FLAT-CONFIG - Ensure presets work with ESLint v9 flat config
+ * @req REQ-PROJECT-INTEGRATION - Support seamless integration via documented preset usage
+ */
+const use_at_your_own_risk_1 = require("eslint/use-at-your-own-risk");
+const index_1 = __importStar(require("../../src/index"));
+const baseConfig = {
+    plugins: {
+        traceability: index_1.default,
+    },
+    rules: {},
+};
+async function lintTextWithConfig(text, config) {
+    const eslint = new use_at_your_own_risk_1.FlatESLint({
+        overrideConfig: config,
+        overrideConfigFile: true,
+        ignore: false,
+    });
+    const [result] = await eslint.lintText(text, { filePath: "example.js" });
+    return result;
+}
+describe("Flat config presets integration (Story 002.0-DEV-ESLINT-CONFIG)", () => {
+    it("[REQ-CONFIG-PRESETS] recommended preset enables traceability rules via documented usage", async () => {
+        const config = [baseConfig, ...index_1.configs.recommended];
+        const code = "function foo() {}";
+        const result = await lintTextWithConfig(code, config);
+        const ruleIds = result.messages.map((m) => m.ruleId).sort();
+        expect(ruleIds).toContain("traceability/require-story-annotation");
+    });
+    it("[REQ-CONFIG-PRESETS] strict preset also enables traceability rules via documented usage", async () => {
+        const config = [baseConfig, ...index_1.configs.strict];
+        const code = "function bar() {}";
+        const result = await lintTextWithConfig(code, config);
+        const ruleIds = result.messages.map((m) => m.ruleId).sort();
+        expect(ruleIds).toContain("traceability/require-story-annotation");
+    });
+});

package/lib/tests/plugin-default-export-and-configs.test.js

@@ -80,12 +80,10 @@ describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", ()
         expect(recommendedRules).toHaveProperty("traceability/require-branch-annotation", "error");
         expect(recommendedRules).toHaveProperty("traceability/valid-story-reference", "error");
         expect(recommendedRules).toHaveProperty("traceability/valid-req-reference", "error");
-        expect(recommendedRules).toHaveProperty("traceability/prefer-implements-annotation", "warn");
     });
     it("[REQ-ERROR-SEVERITY] configs.strict uses same severity mapping as recommended", () => {
         const strictRules = index_1.configs.strict[0].rules;
         const recommendedRules = index_1.configs.recommended[0].rules;
         expect(strictRules).toEqual(recommendedRules);
-        expect(strictRules).toHaveProperty("traceability/prefer-implements-annotation", "warn");
     });
 });

package/lib/tests/rules/prefer-implements-annotation.test.js

@@ -12,6 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  */
 const eslint_1 = require("eslint");
 const prefer_implements_annotation_1 = __importDefault(require("../../src/rules/prefer-implements-annotation"));
+const src_1 = require("../../src");
 const ruleTester = new eslint_1.RuleTester({
     languageOptions: {
         parserOptions: { ecmaVersion: 2020, sourceType: "module" },
@@ -82,3 +83,30 @@ describe("prefer-implements-annotation rule (Story 010.3-DEV-MIGRATE-TO-IMPLEMEN
         ],
     });
 });
+describe("prefer-implements-annotation configuration severity (REQ-CONFIG-SEVERITY)", () => {
+    test("rule is disabled by default in recommended preset (not present in configs.recommended[0].rules)", () => {
+        const recommended = src_1.configs.recommended;
+        expect(Array.isArray(recommended)).toBe(true);
+        const firstConfig = recommended[0];
+        expect(firstConfig).toBeDefined();
+        const rules = firstConfig.rules || {};
+        expect(rules["@eslint-sweat/prefer-implements-annotation"]).toBeUndefined();
+        expect(rules["prefer-implements-annotation"]).toBeUndefined();
+    });
+    test("rule can be configured with severity 'warn' or 'error' in flat config", () => {
+        const flatWarnConfig = {
+            files: ["**/*.ts"],
+            rules: {
+                "prefer-implements-annotation": "warn",
+            },
+        };
+        expect(flatWarnConfig.rules["prefer-implements-annotation"]).toBe("warn");
+        const flatErrorConfig = {
+            files: ["**/*.ts"],
+            rules: {
+                "prefer-implements-annotation": "error",
+            },
+        };
+        expect(flatErrorConfig.rules["prefer-implements-annotation"]).toBe("error");
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "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": {
@@ -67,8 +67,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 +80,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

@@ -13,11 +13,13 @@ Each rule enforces traceability conventions in your code. Below is a summary of
 
 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).
+For a detailed explanation of `@implements` behavior and validation, see [Migration Guide](migration-guide.md) (section **3.1 Multi-story @implements annotations**) and the corresponding `valid-annotation-format` and `valid-req-reference` rule documentation in the plugin's internal docs.
+
+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 `@implements` usage. For rule details and migration guidance, see `docs/rules/prefer-implements-annotation.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 `@implements` annotations as described in `docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md` and `REQ-REQUIRE-ACCEPTS-IMPLEMENTS`, this rule also accepts `@implements` as an alternative way to prove story coverage, so either `@story` or at least one `@implements` 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 `@implements` annotations as described in `docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md` and `REQ-REQUIRE-ACCEPTS-IMPLEMENTS`, this rule also treats `@implements 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.
 
@@ -115,10 +117,10 @@ The `valid-annotation-format` rule is intentionally **backward compatible** with
 - Introduce `@implements` 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:
+Deep requirement checking for both `@req` and `@implements` is handled by the `valid-req-reference` rule in the plugin's internal docs. 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)
+- **Migration guide:** [Migration Guide](migration-guide.md) (section **3.1 Multi-story `@implements` annotations**)
+- **Rule docs:** The `valid-annotation-format` and `valid-req-reference` rule documentation in the plugin's internal docs.
 
 Default Severity: `error`
 Example:
@@ -196,9 +198,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 `@implements` 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 +223,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 +240,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.