eslint-plugin-traceability 1.7.0 → 1.7.1

package/README.md

@@ -54,6 +54,7 @@ module.exports = [
 - `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))
 
 Configuration options: For detailed per-rule options (such as scopes, branch types, and story directory settings), see the individual rule docs in `docs/rules/` and the consolidated [API Reference](user-docs/api-reference.md).
 

package/lib/src/index.d.ts

@@ -14,7 +14,7 @@ import { detectStaleAnnotations, updateAnnotationReferences, batchUpdateAnnotati
  * @story docs/stories/002.0-DYNAMIC-RULE-LOADING.story.md
  * @req REQ-RULE-LIST - Enumerate supported rule file names for plugin discovery
  */
-declare const RULE_NAMES: readonly ["require-story-annotation", "require-req-annotation", "require-branch-annotation", "valid-annotation-format", "valid-story-reference", "valid-req-reference"];
+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>;
 /**
@@ -54,7 +54,7 @@ declare const maintenance: {
 };
 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", Rule.RuleModule>;
+    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: {

package/lib/src/index.js

@@ -17,6 +17,7 @@ const RULE_NAMES = [
     "valid-annotation-format",
     "valid-story-reference",
     "valid-req-reference",
+    "prefer-implements-annotation",
 ];
 const rules = {};
 exports.rules = rules;
@@ -85,6 +86,7 @@ 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

package/lib/src/rules/helpers/valid-annotation-format-internal.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Internal helpers and types for the valid-annotation-format rule.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-MULTILINE-SUPPORT - Handle annotations split across multiple lines
+ * @req REQ-FLEXIBLE-PARSING - Support reasonable variations in whitespace and formatting
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ * @req REQ-IMPLEMENTS-PARSE - Parse @implements annotations without affecting @story/@req
+ * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
+ */
+/**
+ * Pending annotation state tracked while iterating through comment lines.
+ */
+export interface PendingAnnotation {
+    type: "story" | "req";
+    value: string;
+    hasValue: boolean;
+}
+/**
+ * Normalize a raw comment line to make annotation parsing more robust.
+ *
+ * This function trims whitespace, keeps any annotation tags that appear
+ * later in the line, and supports common JSDoc styles such as leading "*".
+ *
+ * It detects @story, @req, and @implements tags while preserving the rest
+ * of the line for downstream logic.
+ */
+export declare function normalizeCommentLine(rawLine: string): string;

package/lib/src/rules/helpers/valid-annotation-format-internal.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Internal helpers and types for the valid-annotation-format rule.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-MULTILINE-SUPPORT - Handle annotations split across multiple lines
+ * @req REQ-FLEXIBLE-PARSING - Support reasonable variations in whitespace and formatting
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ * @req REQ-IMPLEMENTS-PARSE - Parse @implements annotations without affecting @story/@req
+ * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeCommentLine = normalizeCommentLine;
+/**
+ * Normalize a raw comment line to make annotation parsing more robust.
+ *
+ * This function trims whitespace, keeps any annotation tags that appear
+ * later in the line, and supports common JSDoc styles such as leading "*".
+ *
+ * It detects @story, @req, and @implements tags while preserving the rest
+ * of the line for downstream logic.
+ */
+function normalizeCommentLine(rawLine) {
+    const trimmed = rawLine.trim();
+    if (!trimmed) {
+        return "";
+    }
+    const annotationMatch = trimmed.match(/@story\b|@req\b|@implements\b/);
+    if (!annotationMatch || annotationMatch.index === undefined) {
+        const withoutLeadingStar = trimmed.replace(/^\*\s?/, "");
+        return withoutLeadingStar;
+    }
+    return trimmed.slice(annotationMatch.index);
+}

package/lib/src/rules/helpers/valid-implements-utils.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Helpers for @implements annotation validation used by valid-annotation-format.
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-IMPLEMENTS-PARSE - Parse @implements annotations without affecting @story/@req
+ * @req REQ-FORMAT-VALIDATION - Validate @implements story path and requirement IDs
+ * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
+ */
+import type { ResolvedAnnotationOptions } from "./valid-annotation-options";
+/**
+ * Minimum number of tokens required for a valid @implements value:
+ *   - one story path
+ *   - at least one requirement ID
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-IMPLEMENTS-PARSE
+ */
+export declare const MIN_IMPLEMENTS_TOKENS = 2;
+/**
+ * Report a completely missing @implements value (no story path or req IDs).
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-FORMAT-VALIDATION
+ */
+export declare function reportMissingImplementsValue(context: any, comment: any, options: ResolvedAnnotationOptions): void;
+/**
+ * Report a value that has only a story path and no requirement IDs.
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-FORMAT-VALIDATION
+ */
+export declare function reportMissingImplementsReqIds(context: any, comment: any, options: ResolvedAnnotationOptions): void;
+/**
+ * Report an invalid story path inside @implements.
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-FORMAT-VALIDATION
+ */
+export declare function reportInvalidImplementsStoryPath(context: any, comment: any, storyPath: string, options: ResolvedAnnotationOptions): void;
+/**
+ * Report an invalid requirement ID token inside @implements.
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-FORMAT-VALIDATION
+ * @req REQ-MIXED-SUPPORT
+ */
+export declare function reportInvalidImplementsReqId(context: any, comment: any, reqId: string, options: ResolvedAnnotationOptions): void;
+type ImplementsDeps = {
+    MIN_IMPLEMENTS_TOKENS: number;
+    reportMissingImplementsValue: typeof reportMissingImplementsValue;
+    reportMissingImplementsReqIds: typeof reportMissingImplementsReqIds;
+    reportInvalidImplementsStoryPath: typeof reportInvalidImplementsStoryPath;
+    reportInvalidImplementsReqId: typeof reportInvalidImplementsReqId;
+};
+/**
+ * Validate an @implements annotation value.
+ *
+ * This helper encapsulates the logic previously in valid-annotation-format.ts:
+ *   - trims the raw value
+ *   - splits into tokens
+ *   - enforces MIN_IMPLEMENTS_TOKENS
+ *   - validates the story path using options.storyPattern
+ *   - validates each requirement ID using options.reqPattern
+ *   - delegates reporting to the provided helpers
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-IMPLEMENTS-PARSE
+ * @req REQ-FORMAT-VALIDATION
+ * @req REQ-MIXED-SUPPORT
+ */
+export declare function validateImplementsAnnotationHelper(deps: ImplementsDeps, context: any, comment: any, args: {
+    rawValue: string | null | undefined;
+    options: ResolvedAnnotationOptions;
+}): void;
+export {};

package/lib/src/rules/helpers/valid-implements-utils.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIN_IMPLEMENTS_TOKENS = void 0;
+exports.reportMissingImplementsValue = reportMissingImplementsValue;
+exports.reportMissingImplementsReqIds = reportMissingImplementsReqIds;
+exports.reportInvalidImplementsStoryPath = reportInvalidImplementsStoryPath;
+exports.reportInvalidImplementsReqId = reportInvalidImplementsReqId;
+exports.validateImplementsAnnotationHelper = validateImplementsAnnotationHelper;
+const valid_annotation_utils_1 = require("./valid-annotation-utils");
+/**
+ * Minimum number of tokens required for a valid @implements value:
+ *   - one story path
+ *   - at least one requirement ID
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-IMPLEMENTS-PARSE
+ */
+exports.MIN_IMPLEMENTS_TOKENS = 2;
+/**
+ * Report a completely missing @implements value (no story path or req IDs).
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-FORMAT-VALIDATION
+ */
+function reportMissingImplementsValue(context, comment, options) {
+    const { storyExample, reqExample } = options;
+    context.report({
+        node: comment,
+        messageId: "invalidImplementsFormat",
+        data: {
+            details: `Missing story path and requirement IDs for @implements annotation. Expected a value like "${storyExample} ${reqExample}".`,
+        },
+    });
+}
+/**
+ * Report a value that has only a story path and no requirement IDs.
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-FORMAT-VALIDATION
+ */
+function reportMissingImplementsReqIds(context, comment, options) {
+    const { storyExample, reqExample } = options;
+    context.report({
+        node: comment,
+        messageId: "invalidImplementsFormat",
+        data: {
+            details: `Missing requirement IDs for @implements annotation. Expected a value like "${storyExample} ${reqExample}".`,
+        },
+    });
+}
+/**
+ * Report an invalid story path inside @implements.
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-FORMAT-VALIDATION
+ */
+function reportInvalidImplementsStoryPath(context, comment, storyPath, options) {
+    const { storyExample } = options;
+    context.report({
+        node: comment,
+        messageId: "invalidImplementsFormat",
+        data: {
+            details: `Invalid story path "${storyPath}" for @implements annotation. Expected a path like "${storyExample}".`,
+        },
+    });
+}
+/**
+ * Report an invalid requirement ID token inside @implements.
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-FORMAT-VALIDATION
+ * @req REQ-MIXED-SUPPORT
+ */
+function reportInvalidImplementsReqId(context, comment, reqId, options) {
+    context.report({
+        node: comment,
+        messageId: "invalidReqFormat",
+        data: {
+            details: (0, valid_annotation_utils_1.buildReqErrorMessage)("invalid", reqId, options),
+        },
+    });
+}
+/**
+ * Prepare and validate the token array for an @implements value.
+ *
+ * Returns { storyPath, reqIds } when tokens are present and structurally valid,
+ * or null when a missing-value condition has been reported.
+ */
+function parseImplementsTokens(deps, context, comment, rest) {
+    const { MIN_IMPLEMENTS_TOKENS, reportMissingImplementsValue, reportMissingImplementsReqIds, } = deps;
+    const { rawValue, options } = rest;
+    const value = rawValue?.trim() ?? "";
+    if (!value) {
+        reportMissingImplementsValue(context, comment, options);
+        return null;
+    }
+    const tokens = value.split(/\s+/);
+    if (tokens.length < MIN_IMPLEMENTS_TOKENS) {
+        reportMissingImplementsReqIds(context, comment, options);
+        return null;
+    }
+    const [storyPath, ...reqIds] = tokens;
+    return { storyPath, reqIds };
+}
+/**
+ * Validate the parsed storyPath and reqIds against the provided patterns and
+ * delegate reporting of any invalid tokens.
+ */
+function validateImplementsTokens(deps, context, comment, rest) {
+    const { reportInvalidImplementsStoryPath, reportInvalidImplementsReqId } = deps;
+    const { parsed, options } = rest;
+    const { storyPath, reqIds } = parsed;
+    if (!options.storyPattern.test(storyPath)) {
+        reportInvalidImplementsStoryPath(context, comment, storyPath, options);
+        return;
+    }
+    for (const reqId of reqIds) {
+        if (!options.reqPattern.test(reqId)) {
+            reportInvalidImplementsReqId(context, comment, reqId, options);
+        }
+    }
+}
+/**
+ * Validate an @implements annotation value.
+ *
+ * This helper encapsulates the logic previously in valid-annotation-format.ts:
+ *   - trims the raw value
+ *   - splits into tokens
+ *   - enforces MIN_IMPLEMENTS_TOKENS
+ *   - validates the story path using options.storyPattern
+ *   - validates each requirement ID using options.reqPattern
+ *   - delegates reporting to the provided helpers
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-IMPLEMENTS-PARSE
+ * @req REQ-FORMAT-VALIDATION
+ * @req REQ-MIXED-SUPPORT
+ */
+function validateImplementsAnnotationHelper(deps, context, comment, args) {
+    const { rawValue, options } = args;
+    const parsed = parseImplementsTokens(deps, context, comment, {
+        rawValue,
+        options,
+    });
+    if (!parsed) {
+        return;
+    }
+    validateImplementsTokens(deps, context, comment, { parsed, options });
+}

package/lib/src/rules/prefer-implements-annotation.d.ts

@@ -0,0 +1,39 @@
+/**
+ * ESLint rule implementation for preferring the consolidated `@implements`
+ * annotation over legacy combinations of `@story` and `@req` within JSDoc
+ * block comments. This module provides:
+ *
+ * - Detection of legacy `@story` + `@req` patterns.
+ * - Identification of multi-story comment blocks that are not safely
+ *   auto-fixable.
+ * - A conservative auto-fix that rewrites simple, single-story patterns into
+ *   a single `@implements` annotation while preserving formatting.
+ *
+ * The rule is intended as an **optional migration aid** to help projects
+ * gradually move to the newer `@implements` format without breaking existing
+ * traceability links.
+ *
+ * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+ * @req REQ-OPTIONAL-WARNING - Emit configurable recommendation diagnostics for legacy @story/@req usage
+ * @req REQ-MULTI-STORY-DETECT - Detect multi-story patterns that cannot be auto-fixed
+ * @req REQ-SINGLE-STORY-FIX - Restrict auto-fix to single-story, single-path cases
+ * @req REQ-PRESERVE-FORMAT - Preserve original JSDoc indentation and prefix formatting
+ * @req REQ-VALID-OUTPUT - Avoid emitting auto-fixes for complex or ambiguous patterns
+ * @req REQ-BACKWARD-COMP-VALIDATION - Keep legacy @story/@req annotations valid when the rule is disabled
+ * @req REQ-AUTO-FIX - Provide safe, opt-in auto-fix for simple legacy patterns
+ */
+import type { Rule } from "eslint";
+/**
+ * ESLint rule: prefer-implements-annotation
+ *
+ * Recommend migrating from legacy `@story` + `@req` annotations to the
+ * newer `@implements` format. This rule is **disabled by default** and
+ * is intended as an optional, opt-in migration aid.
+ *
+ * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+ * @req REQ-OPTIONAL-WARNING - Emit configurable recommendation diagnostics for legacy @story/@req usage
+ * @req REQ-MULTI-STORY-DETECT - Detect multi-story patterns that cannot be auto-fixed
+ * @req REQ-BACKWARD-COMP-VALIDATION - Keep legacy @story/@req annotations valid when the rule is disabled
+ */
+declare const preferImplementsAnnotationRule: Rule.RuleModule;
+export default preferImplementsAnnotationRule;

package/lib/src/rules/prefer-implements-annotation.js

@@ -0,0 +1,276 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const valid_annotation_format_internal_1 = require("./helpers/valid-annotation-format-internal");
+// Maximum number of distinct @story paths allowed before treating as "multi-story".
+// @req REQ-MULTI-STORY-DETECT - Centralized threshold constant for detecting multi-story patterns
+const MULTI_STORY_THRESHOLD = 1;
+// Minimum number of tokens required for a valid @story annotation line.
+// @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+// @req REQ-MULTI-STORY-DETECT
+const MIN_STORY_TOKENS = 2;
+// Minimum number of tokens required for a valid @req annotation line, aligned with story tokens.
+const MIN_REQ_TOKENS = MIN_STORY_TOKENS;
+// Length of the opening "/*" portion of a block comment prefix.
+const COMMENT_PREFIX_LENGTH = 2;
+function collectStoryAndReqMetadata(comment) {
+    const rawValue = comment.value || "";
+    const rawLines = rawValue.split(/\r?\n/);
+    const storyLineIndices = [];
+    const reqLineIndices = [];
+    const reqIds = [];
+    let storyPath = null;
+    rawLines.forEach((rawLine, index) => {
+        const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(rawLine);
+        if (!normalized)
+            return;
+        if (/^@implements\b/.test(normalized)) {
+            // Mixed @implements usage should have been filtered out earlier
+            return;
+        }
+        if (/^@story\b/.test(normalized)) {
+            const parts = normalized.split(/\s+/);
+            if (parts.length === MIN_STORY_TOKENS) {
+                storyLineIndices.push(index);
+                storyPath = parts[1];
+            }
+            else {
+                storyPath = null;
+            }
+            return;
+        }
+        if (/^@req\b/.test(normalized)) {
+            const parts = normalized.split(/\s+/);
+            if (parts.length === MIN_REQ_TOKENS) {
+                reqLineIndices.push(index);
+                reqIds.push(parts[1]);
+            }
+            else {
+                // Complex @req form; bail out entirely.
+                storyPath = null;
+            }
+        }
+    });
+    return { storyLineIndices, reqLineIndices, reqIds, storyPath };
+}
+function applyImplementsReplacement(context, comment, details) {
+    const { storyIdx, allIndicesToRemove, storyPath, reqIds } = details;
+    const rawValue = comment.value || "";
+    const rawLines = rawValue.split(/\r?\n/);
+    const implAnnotation = `@implements ${storyPath} ${reqIds.join(" ")}`;
+    // Determine the leading prefix (indentation and `*`) from the original @story line
+    const storyRawLine = rawLines[storyIdx];
+    const prefixMatch = storyRawLine.match(/^(\s*\*?\s*)/);
+    const linePrefix = prefixMatch ? prefixMatch[1] : "";
+    const implementsLine = `${linePrefix}${implAnnotation}`;
+    const fixedLines = [];
+    rawLines.forEach((line, index) => {
+        if (index === storyIdx) {
+            fixedLines.push(implementsLine);
+            return;
+        }
+        if (allIndicesToRemove.has(index)) {
+            return;
+        }
+        fixedLines.push(line);
+    });
+    const fixedValue = fixedLines.join("\n");
+    const sourceCode = context.getSourceCode();
+    return (fixer) => fixer.replaceTextRange([comment.range[0], comment.range[1]], sourceCode.text.slice(comment.range[0], comment.range[0] + COMMENT_PREFIX_LENGTH) +
+        fixedValue +
+        "*/");
+}
+/**
+ * Build an ESLint auto-fix for simple single-story `@story` + `@req` JSDoc
+ * blocks, converting them to a single `@implements` annotation while
+ * preserving the original comment formatting.
+ *
+ * The fixer is intentionally conservative and only activates when:
+ * - There is exactly one distinct `@story` path.
+ * - Exactly one `@story` line is present.
+ * - At least one `@req` line is present.
+ * - Each `@req` line has the simple form `@req <REQ-ID>` (no extra tokens).
+ *
+ * When applicable, the fix:
+ * - Removes the original `@story` and `@req` lines.
+ * - Inserts a single `@implements` line in their place, preserving the
+ *   original leading comment prefix (indentation and `*` markers).
+ *
+ * More complex patterns remain diagnostics-only with no fix to avoid
+ * producing invalid or ambiguous output.
+ *
+ * @implements docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+ * @req REQ-AUTO-FIX - Provide safe, opt-in auto-fix for simple legacy patterns
+ * @req REQ-SINGLE-STORY-FIX - Restrict auto-fix to single-story, single-path cases
+ * @req REQ-PRESERVE-FORMAT - Preserve original JSDoc indentation and prefix formatting
+ * @req REQ-VALID-OUTPUT - Avoid emitting auto-fixes for complex or ambiguous patterns
+ */
+function buildImplementsAutoFix(context, comment, storyPaths) {
+    if (storyPaths.size !== 1)
+        return null;
+    const { storyLineIndices, reqLineIndices, reqIds, storyPath } = collectStoryAndReqMetadata(comment);
+    if (storyPaths.size !== 1 ||
+        storyLineIndices.length !== 1 ||
+        reqLineIndices.length < 1 ||
+        storyPath === null) {
+        return null;
+    }
+    const storyIdx = storyLineIndices[0];
+    const allIndicesToRemove = new Set([
+        ...storyLineIndices,
+        ...reqLineIndices,
+    ]);
+    return applyImplementsReplacement(context, comment, {
+        storyIdx,
+        allIndicesToRemove,
+        storyPath,
+        reqIds,
+    });
+}
+function analyzeComment(comment) {
+    const rawLines = (comment.value || "").split(/\r?\n/);
+    let hasStory = false;
+    let hasReq = false;
+    let hasImplements = false;
+    const storyPaths = new Set();
+    rawLines.forEach((rawLine) => {
+        const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(rawLine);
+        if (!normalized)
+            return;
+        if (/^@implements\b/.test(normalized)) {
+            hasImplements = true;
+            return;
+        }
+        if (/^@story\b/.test(normalized)) {
+            hasStory = true;
+            const parts = normalized.split(/\s+/);
+            if (parts.length >= MIN_STORY_TOKENS) {
+                storyPaths.add(parts[1]);
+            }
+            return;
+        }
+        if (/^@req\b/.test(normalized)) {
+            hasReq = true;
+        }
+    });
+    return { hasStory, hasReq, hasImplements, storyPaths };
+}
+function hasMultipleStories(storyPaths) {
+    // @req REQ-MULTI-STORY-DETECT - Use named threshold constant instead of a magic number
+    return storyPaths.size > MULTI_STORY_THRESHOLD;
+}
+function processComment(comment, context) {
+    const { hasStory, hasReq, hasImplements, storyPaths } = analyzeComment(comment);
+    if (!hasStory || !hasReq) {
+        return;
+    }
+    if (hasImplements) {
+        context.report({
+            node: comment,
+            messageId: "cannotAutoFix",
+            data: {
+                reason: "comment mixes @story/@req with existing @implements annotations",
+            },
+        });
+        return;
+    }
+    if (hasMultipleStories(storyPaths)) {
+        context.report({
+            node: comment,
+            messageId: "multiStoryDetected",
+        });
+        return;
+    }
+    const fix = buildImplementsAutoFix(context, comment, storyPaths);
+    context.report({
+        node: comment,
+        messageId: "preferImplements",
+        fix: fix ?? undefined,
+    });
+}
+/**
+ * ESLint rule: prefer-implements-annotation
+ *
+ * Recommend migrating from legacy `@story` + `@req` annotations to the
+ * newer `@implements` format. This rule is **disabled by default** and
+ * is intended as an optional, opt-in migration aid.
+ *
+ * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+ * @req REQ-OPTIONAL-WARNING - Emit configurable recommendation diagnostics for legacy @story/@req usage
+ * @req REQ-MULTI-STORY-DETECT - Detect multi-story patterns that cannot be auto-fixed
+ * @req REQ-BACKWARD-COMP-VALIDATION - Keep legacy @story/@req annotations valid when the rule is disabled
+ */
+const preferImplementsAnnotationRule = {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Recommend using @implements instead of legacy @story + @req annotations (optional migration rule)",
+            recommended: false,
+        },
+        // Auto-fix support will be wired in a later iteration; the rule starts as
+        // a recommendation-only warning with no code modifications.
+        fixable: "code",
+        messages: {
+            /**
+             * Recommend migrating simple, single-story @story + @req blocks to a
+             * single @implements line. Auto-fix is provided where safe in a
+             * follow-up iteration.
+             *
+             * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+             * @req REQ-OPTIONAL-WARNING
+             */
+            preferImplements: "Consider using @implements instead of @story + @req for clearer traceability. Run ESLint with --fix to auto-convert.",
+            /**
+             * Report situations where the rule detects a legacy annotation pattern
+             * but cannot safely provide an automatic fix. The `reason` field gives
+             * a short, human-readable explanation to guide manual migration.
+             *
+             * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+             * @req REQ-MULTI-STORY-DETECT
+             */
+            cannotAutoFix: "Cannot auto-fix: {{reason}}. Manual migration to @implements required.",
+            /**
+             * Specialized message for the most common non-fixable case where more
+             * than one @story annotation appears in the same block, indicating a
+             * likely multi-story integration that must be converted manually.
+             *
+             * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+             * @req REQ-MULTI-STORY-DETECT
+             */
+            multiStoryDetected: "Multiple @story annotations detected in the same comment block. Manually convert to separate @implements lines.",
+        },
+        schema: [],
+    },
+    /**
+     * Rule entrypoint.
+     *
+     * This initial implementation focuses on **detection and messaging only**:
+     * it surfaces recommendations when legacy `@story` + `@req` combinations are
+     * present but does not yet perform automatic code modifications.
+     *
+     * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+     * @req REQ-OPTIONAL-WARNING
+     * @req REQ-MULTI-STORY-DETECT
+     */
+    create(context) {
+        const sourceCode = context.getSourceCode();
+        return {
+            /**
+             * Program-level visitor that scans all comments for legacy
+             * `@story` + `@req` usage and emits recommendation diagnostics.
+             *
+             * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+             * @req REQ-OPTIONAL-WARNING - Emit recommendations when legacy annotations are detected
+             * @req REQ-MULTI-STORY-DETECT - Detect multi-story and mixed annotation patterns
+             */
+            Program() {
+                const comments = sourceCode.getAllComments() || [];
+                comments
+                    .filter((comment) => comment.type === "Block")
+                    .forEach((comment) => {
+                    processComment(comment, context);
+                });
+            },
+        };
+    },
+};
+exports.default = preferImplementsAnnotationRule;

package/lib/src/rules/valid-annotation-format.js

@@ -2,34 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const valid_annotation_options_1 = require("./helpers/valid-annotation-options");
 const valid_annotation_utils_1 = require("./helpers/valid-annotation-utils");
-/**
- * Normalize a raw comment line to make annotation parsing more robust.
- *
- * This function trims whitespace, keeps any annotation tags that appear
- * later in the line, and supports common JSDoc styles such as leading "*".
- *
- * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
- * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @req REQ-FLEXIBLE-PARSING - Support reasonable variations in whitespace and formatting
- * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
- */
-function normalizeCommentLine(rawLine) {
-    const trimmed = rawLine.trim();
-    if (!trimmed) {
-        return "";
-    }
-    const annotationMatch = trimmed.match(/@story\b|@req\b/);
-    if (!annotationMatch || annotationMatch.index === undefined) {
-        const withoutLeadingStar = trimmed.replace(/^\*\s?/, "");
-        return withoutLeadingStar;
-    }
-    return trimmed.slice(annotationMatch.index);
-}
+const valid_implements_utils_1 = require("./helpers/valid-implements-utils");
+const valid_annotation_format_internal_1 = require("./helpers/valid-annotation-format-internal");
 /**
  * Report an invalid @story annotation without applying a fix.
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  */
 function reportInvalidStoryFormat(context, comment, collapsed, options) {
@@ -91,6 +71,7 @@ function createStoryFix(context, comment, fixed) {
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-PATH-FORMAT - Validate @story paths follow expected patterns
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  * @req REQ-AUTOFIX-SAFE - Auto-fix must be conservative and avoid changing semantics
@@ -117,11 +98,13 @@ function reportInvalidStoryFormatWithFix(context, comment, collapsed, fixed) {
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-PATH-FORMAT - Validate @story paths follow expected patterns
  * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  * @req REQ-REGEX-VALIDATION - Validate configurable story regex patterns and fall back safely
  * @req REQ-BACKWARD-COMP - Preserve behavior when invalid regex config is supplied
+ * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
  */
 function validateStoryAnnotation(context, comment, rawValue, options) {
     const trimmed = rawValue.trim();
@@ -154,10 +137,12 @@ function validateStoryAnnotation(context, comment, rawValue, options) {
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-REQ-FORMAT - Validate @req identifiers follow expected patterns
  * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
  * @req REQ-REGEX-VALIDATION - Validate configurable requirement regex patterns and fall back safely
  * @req REQ-BACKWARD-COMP - Preserve behavior when invalid regex config is supplied
+ * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
  */
 function validateReqAnnotation(context, comment, rawValue, options) {
     const trimmed = rawValue.trim();
@@ -179,13 +164,47 @@ function validateReqAnnotation(context, comment, rawValue, options) {
         });
     }
 }
+/**
+ * Validate an @implements annotation value and report detailed errors when needed.
+ *
+ * Expected format:
+ *   @implements <storyPath> <REQ-ID> [<REQ-ID> ...]
+ *
+ * Validation rules:
+ *   - Value must include at least a story path and one requirement ID.
+ *   - Story path must match the same storyPattern used for @story (no auto-fix).
+ *   - Each subsequent token must match reqPattern and is validated individually.
+ *
+ * Story path issues are reported with "invalidImplementsFormat" and
+ * requirement ID issues reuse the existing "invalidReqFormat" message.
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-IMPLEMENTS-PARSE - Parse @implements annotations without affecting @story/@req
+ * @req REQ-FORMAT-VALIDATION - Validate @implements story path and requirement IDs
+ * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
+ */
+function validateImplementsAnnotation(context, comment, rawValue, options) {
+    const deps = {
+        MIN_IMPLEMENTS_TOKENS: valid_implements_utils_1.MIN_IMPLEMENTS_TOKENS,
+        reportMissingImplementsReqIds: valid_implements_utils_1.reportMissingImplementsReqIds,
+        reportMissingImplementsValue: valid_implements_utils_1.reportMissingImplementsValue,
+        reportInvalidImplementsReqId: valid_implements_utils_1.reportInvalidImplementsReqId,
+        reportInvalidImplementsStoryPath: valid_implements_utils_1.reportInvalidImplementsStoryPath,
+    };
+    (0, valid_implements_utils_1.validateImplementsAnnotationHelper)(deps, context, comment, {
+        rawValue,
+        options,
+    });
+}
 /**
  * Finalize and validate the currently pending annotation, if any.
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-SYNTAX-VALIDATION - Validate annotation syntax matches specification
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
  */
 function finalizePendingAnnotation(context, comment, options, pending) {
     if (!pending) {
@@ -193,8 +212,10 @@ function finalizePendingAnnotation(context, comment, options, pending) {
     }
     // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
     // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+    // @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
     // @req REQ-SYNTAX-VALIDATION - Dispatch validation based on annotation type
     // @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+    // @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
     if (pending.type === "story") {
         validateStoryAnnotation(context, comment, pending.value, options);
     }
@@ -208,9 +229,13 @@ function finalizePendingAnnotation(context, comment, options, pending) {
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-SYNTAX-VALIDATION - Start new pending annotation when a tag is found
  * @req REQ-MULTILINE-SUPPORT - Treat subsequent lines as continuation for pending annotation
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ * @req REQ-IMPLEMENTS-PARSE - Parse @implements annotations without affecting @story/@req
+ * @req REQ-FORMAT-VALIDATION - Validate @implements story path and requirement IDs
+ * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
  */
 function processCommentLine({ normalized, pending, context, comment, options, }) {
     if (!normalized) {
@@ -218,10 +243,19 @@ function processCommentLine({ normalized, pending, context, comment, options, })
     }
     const isStory = /@story\b/.test(normalized);
     const isReq = /@req\b/.test(normalized);
+    const isImplements = /@implements\b/.test(normalized);
+    // Handle @implements as an immediate, single-line annotation
+    if (isImplements) {
+        const implementsValue = normalized.replace(/^@implements\b/, "").trim();
+        validateImplementsAnnotation(context, comment, implementsValue, options);
+        return pending;
+    }
     // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
     // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+    // @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
     // @req REQ-SYNTAX-VALIDATION - Start new pending annotation when a tag is found
     // @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+    // @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
     if (isStory || isReq) {
         finalizePendingAnnotation(context, comment, options, pending);
         const value = normalized.replace(/^@story\b|^@req\b/, "").trim();
@@ -233,8 +267,10 @@ function processCommentLine({ normalized, pending, context, comment, options, })
     }
     // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
     // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+    // @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
     // @req REQ-MULTILINE-SUPPORT - Treat subsequent lines as continuation for pending annotation
     // @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+    // @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
     if (pending) {
         const continuation = normalized.trim();
         if (!continuation) {
@@ -252,23 +288,30 @@ function processCommentLine({ normalized, pending, context, comment, options, })
     return pending;
 }
 /**
- * Process a single comment node and validate any @story/@req annotations it contains.
+ * Process a single comment node and validate any @story/@req/@implements annotations it contains.
  *
- * Supports annotations whose values span multiple lines within the same
+ * Supports @story and @req annotations whose values span multiple lines within the same
  * comment block, collapsing whitespace so that the logical value can be
  * validated against the configured patterns.
  *
+ * @implements annotations are validated immediately per-line and are not
+ * accumulated into pending multi-line state.
+ *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-MULTILINE-SUPPORT - Handle annotations split across multiple lines
  * @req REQ-FLEXIBLE-PARSING - Support reasonable variations in whitespace and formatting
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ * @req REQ-IMPLEMENTS-PARSE - Parse @implements annotations without affecting @story/@req
+ * @req REQ-FORMAT-VALIDATION - Validate @implements story path and requirement IDs
+ * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
  */
 function processComment(context, comment, options) {
     const rawLines = (comment.value || "").split(/\r?\n/);
     let pending = null;
     rawLines.forEach((rawLine) => {
-        const normalized = normalizeCommentLine(rawLine);
+        const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(rawLine);
         pending = processCommentLine({
             normalized,
             pending,
@@ -283,7 +326,7 @@ exports.default = {
     meta: {
         type: "problem",
         docs: {
-            description: "Validate format and syntax of @story and @req annotations",
+            description: "Validate format and syntax of @story, @req, and @implements annotations",
             recommended: "error",
         },
         messages: {
@@ -301,6 +344,14 @@ exports.default = {
              * @req REQ-ERROR-CONSISTENCY - Use shared "Invalid annotation format: {{details}}." message pattern across rules
              */
             invalidReqFormat: "Invalid annotation format: {{details}}.",
+            /**
+             * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+             * @req REQ-ERROR-SPECIFIC - Provide specific details about invalid @implements annotation format
+             * @req REQ-ERROR-CONTEXT - Include human-readable details about the expected @implements annotation format
+             * @req REQ-ERROR-CONSISTENCY - Use shared "Invalid annotation format: {{details}}." message pattern across rules
+             * @req REQ-FORMAT-VALIDATION - Validate @implements story path and requirement IDs
+             */
+            invalidImplementsFormat: "Invalid annotation format: {{details}}.",
             /**
              * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
              * @req REQ-REGEX-VALIDATION - Surface configuration errors for invalid regex patterns
@@ -326,11 +377,15 @@ exports.default = {
      * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
      * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
      * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+     * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
      * @req REQ-SYNTAX-VALIDATION - Ensure rule create function validates annotations syntax
      * @req REQ-FORMAT-SPECIFICATION - Implement formatting checks per specification
      * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
      * @req REQ-REGEX-VALIDATION - Derive validation regexes from shared options helper
      * @req REQ-BACKWARD-COMP - Fall back to default patterns and continue validation on config errors
+     * @req REQ-IMPLEMENTS-PARSE - Parse @implements annotations without affecting @story/@req
+     * @req REQ-FORMAT-VALIDATION - Validate @implements story path and requirement IDs
+     * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
      */
     create(context) {
         const sourceCode = context.getSourceCode();
@@ -338,16 +393,20 @@ exports.default = {
         const optionErrors = (0, valid_annotation_options_1.getOptionErrors)();
         return {
             /**
-             * Program-level handler that inspects all comments for @story and @req tags
+             * Program-level handler that inspects all comments for @story, @req, and @implements tags
              *
              * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
              * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
              * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+             * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
              * @req REQ-PATH-FORMAT - Validate @story paths follow expected patterns
              * @req REQ-REQ-FORMAT - Validate @req identifiers follow expected patterns
              * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
              * @req REQ-REGEX-VALIDATION - Surface regex configuration errors without blocking validation
              * @req REQ-BACKWARD-COMP - Continue validating comments using default patterns on error
+             * @req REQ-IMPLEMENTS-PARSE - Parse @implements annotations without affecting @story/@req
+             * @req REQ-FORMAT-VALIDATION - Validate @implements story path and requirement IDs
+             * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
              */
             Program(node) {
                 if (optionErrors && optionErrors.length > 0) {

package/lib/src/rules/valid-req-reference.js

@@ -14,6 +14,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
  */
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+/**
+ * Token index configuration for @implements annotations.
+ * This clarifies the expected positions of the story path and first requirement ID
+ * and avoids hard-coded "magic number" indices in parsing logic.
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ */
+const IMPLEMENTS_TOKENS = {
+    STORY_INDEX: 1,
+    FIRST_REQ_INDEX: 2,
+};
 /**
  * Extract the story path from a JSDoc comment.
  * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
@@ -164,11 +174,68 @@ function validateReqLine(opts) {
         reqSet,
     });
 }
+/**
+ * Parse an @implements annotation line into its story path and requirement IDs.
+ * Expects the format: "@implements <storyPath> <REQ-ID-1> <REQ-ID-2> ..."
+ * Invalid formats (missing storyPath or reqIds) are ignored by this deep rule.
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-IMPLEMENTS-VALIDATE - Support validation of @implements annotations
+ * @req REQ-MIXED-SUPPORT - Allow mixed @story/@req/@implements usage in the same comment
+ * @req REQ-SCOPED-IDS - Treat requirement IDs as scoped to the referenced story file
+ */
+function parseImplementsLine(line) {
+    const parts = line.split(/\s+/);
+    const storyPath = parts[IMPLEMENTS_TOKENS.STORY_INDEX];
+    const reqIds = parts.slice(IMPLEMENTS_TOKENS.FIRST_REQ_INDEX);
+    if (!storyPath || reqIds.length === 0) {
+        return null;
+    }
+    return { storyPath, reqIds };
+}
+/**
+ * Validate an @implements annotation line against the referenced story content.
+ * Performs path validation, file reading, caching, and requirement existence checks
+ * for each requirement ID listed on the line.
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-IMPLEMENTS-VALIDATE - Validate that all @implements requirement IDs exist
+ * @req REQ-MIXED-SUPPORT - Ensure @implements can coexist with @story/@req annotations
+ * @req REQ-SCOPED-IDS - Validate requirement IDs in the scope of their explicit story
+ */
+function validateImplementsLine(opts) {
+    const { comment, context, line, cwd, reqCache } = opts;
+    const parsed = parseImplementsLine(line);
+    if (!parsed) {
+        return;
+    }
+    const { storyPath, reqIds } = parsed;
+    const { reqSet } = resolveStoryAndRequirements({
+        comment,
+        context,
+        storyPath,
+        cwd,
+        reqCache,
+    });
+    if (!reqSet) {
+        return;
+    }
+    for (const reqId of reqIds) {
+        checkRequirementExists({
+            comment,
+            context,
+            reqId,
+            storyPath,
+            reqSet,
+        });
+    }
+}
 /**
  * Handle a single annotation line for story or requirement metadata.
  * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
  * @req REQ-DEEP-PARSE - Parse annotation lines for @story and @req tags
  * @req REQ-DEEP-MATCH - Dispatch @req lines for validation against story requirements
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-IMPLEMENTS-VALIDATE - Dispatch @implements lines for validation
+ * @req REQ-MIXED-SUPPORT - Support mixed annotation types without interfering with each other
  */
 function handleAnnotationLine(opts) {
     const { line, comment, context, cwd, reqCache, storyPath } = opts;
@@ -180,6 +247,10 @@ function handleAnnotationLine(opts) {
         validateReqLine({ comment, context, line, storyPath, cwd, reqCache });
         return storyPath;
     }
+    else if (line.startsWith("@implements")) {
+        validateImplementsLine({ comment, context, line, cwd, reqCache });
+        return storyPath;
+    }
     return storyPath;
 }
 /**

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

@@ -55,6 +55,7 @@ describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", ()
             "valid-annotation-format",
             "valid-story-reference",
             "valid-req-reference",
+            "prefer-implements-annotation",
         ];
         // Act: get actual rule names from plugin
         const actual = Object.keys(index_1.rules);
@@ -79,10 +80,12 @@ 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.d.ts

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

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

@@ -0,0 +1,84 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Tests for: docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+ * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+ * @req REQ-OPTIONAL-WARNING - Verify rule emits recommendations for legacy @story/@req usage
+ * @req REQ-MULTI-STORY-DETECT - Verify rule detects multi-story and mixed-annotation patterns
+ * @req REQ-CONFIG-SEVERITY - Verify rule is disabled by default and can be enabled as warn/error
+ */
+const eslint_1 = require("eslint");
+const prefer_implements_annotation_1 = __importDefault(require("../../src/rules/prefer-implements-annotation"));
+const ruleTester = new eslint_1.RuleTester({
+    languageOptions: {
+        parserOptions: { ecmaVersion: 2020, sourceType: "module" },
+    },
+});
+describe("prefer-implements-annotation rule (Story 010.3-DEV-MIGRATE-TO-IMPLEMENTS)", () => {
+    ruleTester.run("prefer-implements-annotation", prefer_implements_annotation_1.default, {
+        valid: [
+            {
+                name: "[REQ-BACKWARD-COMP-VALIDATION] comment with only @story is ignored",
+                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction onlyStory() {}`,
+            },
+            {
+                name: "[REQ-BACKWARD-COMP-VALIDATION] comment with only @req is ignored",
+                code: `/**\n * @req REQ-ONLY\n */\nfunction onlyReq() {}`,
+            },
+            {
+                name: "[REQ-BACKWARD-COMP-VALIDATION] comment with @implements only is ignored",
+                code: `/**\n * @implements docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction alreadyImplements() {}`,
+            },
+        ],
+        invalid: [
+            {
+                name: "[REQ-OPTIONAL-WARNING] single-story @story + @req block triggers preferImplements message",
+                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction legacy() {}`,
+                output: `/**\n * @implements docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction legacy() {}`,
+                errors: [{ messageId: "preferImplements" }],
+            },
+            {
+                name: "[REQ-MULTI-STORY-DETECT] mixed @story/@req and @implements triggers cannotAutoFix",
+                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n * @implements docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction mixed() {}`,
+                errors: [
+                    {
+                        messageId: "cannotAutoFix",
+                        data: {
+                            reason: "comment mixes @story/@req with existing @implements annotations",
+                        },
+                    },
+                ],
+            },
+            {
+                name: "[REQ-MULTI-STORY-DETECT] multiple @story paths in same block trigger multiStoryDetected",
+                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md\n * @req REQ-BRANCH-DETECTION\n */\nfunction multiStory() {}`,
+                errors: [{ messageId: "multiStoryDetected" }],
+            },
+            {
+                name: "[REQ-AUTO-FIX] single @story + single @req auto-fixes to single @implements line",
+                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction autoFixSingleReq() {}`,
+                output: `/**\n * @implements docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction autoFixSingleReq() {}`,
+                errors: [{ messageId: "preferImplements" }],
+            },
+            {
+                name: "[REQ-SINGLE-STORY-FIX] single @story with multiple @req lines auto-fixes to single @implements line containing all REQ IDs",
+                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ONE\n * @req REQ-TWO\n * @req REQ-THREE\n */\nfunction autoFixMultiReq() {}`,
+                output: `/**\n * @implements docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ONE REQ-TWO REQ-THREE\n */\nfunction autoFixMultiReq() {}`,
+                errors: [{ messageId: "preferImplements" }],
+            },
+            {
+                name: "[REQ-AUTO-FIX] complex @req content (extra description) does not auto-fix but still warns",
+                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED must handle extra description\n */\nfunction complexReqNoAutoFix() {}`,
+                errors: [{ messageId: "preferImplements" }],
+            },
+            {
+                name: "[REQ-AUTO-FIX] complex @story content (extra description) does not auto-fix but still warns",
+                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md additional descriptive text\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction complexStoryNoAutoFix() {}`,
+                errors: [{ messageId: "preferImplements" }],
+            },
+        ],
+    });
+});

package/lib/tests/rules/valid-annotation-format.test.js

@@ -18,6 +18,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @req REQ-CONFIGURABLE-PATTERNS-REQ - Rule supports configurable requirement ID regex patterns
  * @req REQ-CONFIGURABLE-PATTERNS-EXAMPLES - Rule supports configurable example strings in error messages
  * @req REQ-CONFIGURABLE-PATTERNS-FALLBACK - Invalid regex patterns fall back to default behavior without crashing
+ * Tests for: docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-IMPLEMENTS-PARSE - Rule parses @implements annotations with story and requirement references
+ * @req REQ-FORMAT-VALIDATION - Rule validates story and requirement formats inside @implements annotations
+ * @req REQ-MIXED-SUPPORT - Rule supports mixed @story/@req/@implements usage in the same comment
  */
 const eslint_1 = require("eslint");
 const valid_annotation_format_1 = __importDefault(require("../../src/rules/valid-annotation-format"));
@@ -168,6 +173,27 @@ describe("Valid Annotation Format Rule (Story 005.0-DEV-ANNOTATION-VALIDATION)",
                     },
                 ],
             },
+            {
+                name: "[REQ-IMPLEMENTS-PARSE] valid single @implements with one story and one requirement (default patterns)",
+                code: `/**
+ * @implements docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md REQ-IMPLEMENTS-PARSE
+ */`,
+            },
+            {
+                name: "[REQ-IMPLEMENTS-PARSE] valid multiple @implements lines with different stories and requirements",
+                code: `/**
+ * @implements docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md REQ-IMPLEMENTS-PARSE REQ-FORMAT-VALIDATION
+ * @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-FORMAT-SPECIFICATION
+ */`,
+            },
+            {
+                name: "[REQ-MIXED-SUPPORT] valid mixed @story/@req/@implements usage in same block comment",
+                code: `/**
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-MIXED-SUPPORT
+ * @implements docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md REQ-IMPLEMENTS-PARSE REQ-FORMAT-VALIDATION REQ-MIXED-SUPPORT
+ */`,
+            },
         ],
         invalid: [
             makeInvalidStory({
@@ -480,6 +506,58 @@ describe("Valid Annotation Format Rule (Story 005.0-DEV-ANNOTATION-VALIDATION)",
                     },
                 ],
             },
+            makeInvalid({
+                name: "[REQ-IMPLEMENTS-PARSE] @implements with no value is invalid",
+                code: `/**
+ * @implements
+ */`,
+                messageId: "invalidImplementsFormat",
+                details: 'Missing story path and requirement IDs for @implements annotation. Expected a value like "docs/stories/005.0-DEV-EXAMPLE.story.md REQ-EXAMPLE".',
+            }),
+            makeInvalid({
+                name: "[REQ-IMPLEMENTS-PARSE] @implements with only story path and no requirement IDs is invalid",
+                code: `/**
+ * @implements docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ */`,
+                messageId: "invalidImplementsFormat",
+                details: 'Missing requirement IDs for @implements annotation. Expected a value like "docs/stories/005.0-DEV-EXAMPLE.story.md REQ-EXAMPLE".',
+            }),
+            makeInvalid({
+                name: "[REQ-FORMAT-VALIDATION] @implements with invalid story path format",
+                code: `/**
+ * @implements invalid/path.txt REQ-IMPLEMENTS-PARSE
+ */`,
+                messageId: "invalidImplementsFormat",
+                details: 'Invalid story path "invalid/path.txt" for @implements annotation. Expected a path like "docs/stories/005.0-DEV-EXAMPLE.story.md".',
+            }),
+            {
+                name: "[REQ-FORMAT-VALIDATION] @implements with invalid requirement ID format",
+                code: `/**
+ * @implements docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md REQ-VALID invalid-format
+ */`,
+                errors: [
+                    {
+                        messageId: "invalidReqFormat",
+                        data: {
+                            details: 'Invalid requirement ID "invalid-format" for @req annotation. Expected an identifier like "REQ-EXAMPLE" (uppercase letters, numbers, and dashes only).',
+                        },
+                    },
+                ],
+            },
+            {
+                name: "[REQ-FORMAT-VALIDATION] @implements with multiple requirement IDs where one is invalid",
+                code: `/**
+ * @implements docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md REQ-VALID-1 REQ-VALID-2 bad-id
+ */`,
+                errors: [
+                    {
+                        messageId: "invalidReqFormat",
+                        data: {
+                            details: 'Invalid requirement ID "bad-id" for @req annotation. Expected an identifier like "REQ-EXAMPLE" (uppercase letters, numbers, and dashes only).',
+                        },
+                    },
+                ],
+            },
         ],
     });
 });

package/lib/tests/rules/valid-req-reference.test.js

@@ -32,6 +32,15 @@ describe("Valid Req Reference Rule (Story 010.0-DEV-DEEP-VALIDATION)", () => {
                 code: `// @story tests/fixtures/story_bullet.md
 // @req REQ-BULLET-LIST`,
             },
+            {
+                name: "[REQ-DEEP-IMPLEMENTS] single implements line with multiple requirements in multi-story fixture (see 010.2-DEV-MULTI-STORY-SUPPORT)",
+                code: `// @implements tests/fixtures/story_multi_a.md REQ-SHARED-ID REQ-ONLY-A`,
+            },
+            {
+                name: "[REQ-DEEP-IMPLEMENTS] multi-story implements with shared requirement IDs (see 010.2-DEV-MULTI-STORY-SUPPORT)",
+                code: `// @implements tests/fixtures/story_multi_a.md REQ-SHARED-ID REQ-ONLY-A
+// @implements tests/fixtures/story_multi_b.md REQ-SHARED-ID REQ-ONLY-B`,
+            },
         ],
         invalid: [
             {
@@ -88,6 +97,31 @@ describe("Valid Req Reference Rule (Story 010.0-DEV-DEEP-VALIDATION)", () => {
                     },
                 ],
             },
+            {
+                name: "[REQ-DEEP-IMPLEMENTS] missing implements requirement in multi-story fixture (see 010.2-DEV-MULTI-STORY-SUPPORT)",
+                code: `// @implements tests/fixtures/story_multi_a.md REQ-NOT-IN-A`,
+                errors: [
+                    {
+                        messageId: "reqMissing",
+                        data: {
+                            reqId: "REQ-NOT-IN-A",
+                            storyPath: "tests/fixtures/story_multi_a.md",
+                        },
+                    },
+                ],
+            },
+            {
+                name: "[REQ-DEEP-IMPLEMENTS] disallow path traversal in implements story path (see 010.2-DEV-MULTI-STORY-SUPPORT)",
+                code: `// @implements ../tests/fixtures/story_multi_a.md REQ-SHARED-ID`,
+                errors: [
+                    {
+                        messageId: "invalidPath",
+                        data: {
+                            storyPath: "../tests/fixtures/story_multi_a.md",
+                        },
+                    },
+                ],
+            },
         ],
     });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.7.0",
+  "version": "1.7.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",