eslint-plugin-traceability 1.25.0 → 1.27.0

package/CHANGELOG.md

@@ -1,9 +1,10 @@
-# [1.25.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.24.0...v1.25.0) (2026-01-10)
+# [1.27.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.26.0...v1.27.0) (2026-01-12)
 
 
 ### Features
 
-* **maintenance:** add ESLint config integration and circular reference detection ([44d1dd9](https://github.com/voder-ai/eslint-plugin-traceability/commit/44d1dd9f11c7e9fa03c5077d43fec837a6aaea36))
+* **rules:** add storyDirectories support to valid-annotation-format ([50ac131](https://github.com/voder-ai/eslint-plugin-traceability/commit/50ac131f24accf3009899939ababc91c0f1c83ad)), closes [#now-1](https://github.com/voder-ai/eslint-plugin-traceability/issues/now-1)
+* **rules:** complete storyDirectories example derivation ([ac0ed9c](https://github.com/voder-ai/eslint-plugin-traceability/commit/ac0ed9c48c5312c502ae07d18b1ab0ca36e6e2c0))
 
 # Changelog
 

package/README.md

@@ -292,41 +292,40 @@ Practical usage examples and sample configurations are available in the [Example
 
 ## Maintenance CLI
 
-The `traceability-maint` CLI helps you maintain and audit `@story` annotations outside of ESLint runs. It focuses on repository-wide checks for stale story references and safe batch updates.
+The `traceability-maint` CLI provides a batch update tool for maintaining `@story` and `@supports` annotation references when you reorganize story files.
 
-### Commands
+**Note**: Detection and verification of stale references are already handled by ESLint rules (`valid-story-reference`, `valid-req-reference`) during normal linting. The maintenance CLI's primary value is the **update** command, which can batch-update references across your codebase when story files are moved or renamed - something ESLint's auto-fix cannot do.
 
-- `detect` – Scan the workspace and detect `@story` annotations that reference missing story files.
-- `verify` – Verify that no stale `@story` annotations exist under the workspace root.
-- `report` – Generate a human-readable or JSON report of stale story references and circular dependencies.
-- `update` – Apply safe, scripted updates to `@story` annotations (e.g., when a story file is renamed).
+### Primary Command
 
-### Usage
+- `update` – Batch update `@story` and `@supports` annotations when a story file is renamed or moved (the key feature ESLint cannot provide)
 
-All commands are run from your project root:
+### Supporting Commands
 
-```bash
-# Show help and all options
-npx traceability-maint --help
+The CLI also includes `detect`, `verify`, and `report` commands for historical compatibility, but these largely duplicate what ESLint already provides during normal linting:
 
-# Detect stale story references
-npx traceability-maint detect --root .
+- `detect` – Scan for `@story` annotations referencing missing files (ESLint rules already do this)
+- `verify` – Check for stale annotations (ESLint rules already do this)
+- `report` – Generate reports of stale references (ESLint output already provides this)
 
-# Detect with ESLint-style ignore patterns
-npx traceability-maint detect --root . --ignore-pattern node_modules --ignore-pattern dist
-
-# Verify that annotations are valid
-npx traceability-maint verify --root .
+### Usage
 
-# Generate a JSON report for CI pipelines
-npx traceability-maint report --root . --format json
+**Primary use case - batch update references:**
 
+```bash
 # Update references when a story file is renamed
 npx traceability-maint update \
   --root . \
   --from "stories/feature-authentication.story.md" \
   --to "stories/feature-auth-v2.story.md"
 
+# Preview changes first with --dry-run
+npx traceability-maint update \
+  --root . \
+  --from "stories/old.story.md" \
+  --to "stories/new.story.md" \
+  --dry-run
+
 # Update with ignore patterns to skip generated code
 npx traceability-maint update \
   --root . \
@@ -335,6 +334,25 @@ npx traceability-maint update \
   --ignore-pattern dist
 ```
 
+**Supporting commands** (largely redundant with ESLint, but available):
+
+```bash
+# Show help and all options
+npx traceability-maint --help
+
+# Detect stale story references (ESLint already does this during linting)
+npx traceability-maint detect --root .
+
+# Detect with ESLint-style ignore patterns
+npx traceability-maint detect --root . --ignore-pattern node_modules --ignore-pattern dist
+
+# Verify that annotations are valid (ESLint already does this during linting)
+npx traceability-maint verify --root .
+
+# Generate a report (ESLint output already provides this information)
+npx traceability-maint report --root . --format json
+```
+
 ### Options
 
 - `--root <path>` – Workspace root directory (defaults to current directory)
@@ -347,7 +365,7 @@ npx traceability-maint update \
 
 ### ESLint Configuration Integration
 
-The maintenance tools support integration with ESLint configuration through `--ignore-pattern` flags. This allows you to:
+The maintenance tools support `--ignore-pattern` flags to skip directories when performing batch updates:
 
 - Skip generated code directories (e.g., `dist`, `build`)
 - Ignore dependency folders (e.g., `node_modules`)
@@ -356,15 +374,26 @@ The maintenance tools support integration with ESLint configuration through `--i
 Multiple patterns can be specified:
 
 ```bash
-npx traceability-maint detect \
+npx traceability-maint update \
+  --from old.story.md \
+  --to new.story.md \
   --ignore-pattern node_modules \
   --ignore-pattern dist \
   --ignore-pattern coverage
 ```
 
-### Circular Reference Detection
+### When to Use the Maintenance CLI vs ESLint
+
+**Use the maintenance CLI** when:
+- You've renamed or moved story files and need to update all code references
+- You're reorganizing your story file structure
+
+**Use ESLint** for:
+- Detecting stale or invalid references during development
+- Validating annotation format
+- Ongoing verification of traceability compliance
 
-The `report` command now includes detection of circular `@story` references in your story files. Circular references occur when story files reference each other in a cycle (e.g., A → B → A or A → B → C → A). These are reported separately in the maintenance report output to help identify potential documentation issues.
+The maintenance CLI is a manual refactoring aid, not an automated validation tool. ESLint handles validation automatically during your normal development workflow.
 
 For a full description of options and JSON payloads, see the [Maintenance API and CLI](user-docs/api-reference.md#maintenance-api-and-cli) section in the API Reference.
 

package/lib/maintenance/batch.d.ts

@@ -5,15 +5,19 @@ import { GetAllFilesOptions } from "./utils";
  * @req REQ-MAINT-BATCH - Perform batch updates
  * @req REQ-MAINT-VERIFY - Verify annotation references
  * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
+ * @req REQ-MAINT-UPDATE#1 - Update @supports references alongside @story
  * @param codebasePath Absolute path to the workspace root where annotations will be updated.
  * @param mappings Array of mapping objects describing path changes, each containing an oldPath and newPath.
  * @param options Optional configuration including ESLint ignore patterns
- * @returns Total number of updated @story annotations across all mappings.
+ * @returns Object with total count of updated annotations and array of malformed annotation warnings
  */
 export declare function batchUpdateAnnotations(codebasePath: string, mappings: {
     oldPath: string;
     newPath: string;
-}[], options?: GetAllFilesOptions): number;
+}[], options?: GetAllFilesOptions): {
+    count: number;
+    warnings: string[];
+};
 /**
  * Verify annotation references in codebase after maintenance operations
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md

package/lib/maintenance/batch.js

@@ -10,17 +10,21 @@ const detect_1 = require("./detect");
  * @req REQ-MAINT-BATCH - Perform batch updates
  * @req REQ-MAINT-VERIFY - Verify annotation references
  * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
+ * @req REQ-MAINT-UPDATE#1 - Update @supports references alongside @story
  * @param codebasePath Absolute path to the workspace root where annotations will be updated.
  * @param mappings Array of mapping objects describing path changes, each containing an oldPath and newPath.
  * @param options Optional configuration including ESLint ignore patterns
- * @returns Total number of updated @story annotations across all mappings.
+ * @returns Object with total count of updated annotations and array of malformed annotation warnings
  */
 function batchUpdateAnnotations(codebasePath, mappings, options) {
     let totalUpdated = 0;
+    const allWarnings = [];
     for (const { oldPath, newPath } of mappings) {
-        totalUpdated += (0, update_1.updateAnnotationReferences)(codebasePath, oldPath, newPath, options);
+        const result = (0, update_1.updateAnnotationReferences)(codebasePath, oldPath, newPath, options);
+        totalUpdated += result.count;
+        allWarnings.push(...result.warnings);
     }
-    return totalUpdated;
+    return { count: totalUpdated, warnings: allWarnings };
 }
 /**
  * Verify annotation references in codebase after maintenance operations

package/lib/maintenance/commands.js

@@ -106,6 +106,33 @@ function handleReport(normalized) {
     }
     return exports.EXIT_OK;
 }
+/**
+ * Handle dry-run mode for update command
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE
+ */
+function handleUpdateDryRun(root, from, to, flags) {
+    const options = flags.ignorePatterns
+        ? { ignorePatterns: flags.ignorePatterns }
+        : undefined;
+    const beforeReport = (0, report_1.generateMaintenanceReport)(root, options);
+    const potentialChanges = beforeReport ? beforeReport.split("\n").length : 0;
+    const summary = {
+        root,
+        from,
+        to,
+        estimatedStaleCount: potentialChanges,
+    };
+    if (flags.json) {
+        console.log(JSON.stringify({ mode: "dry-run", ...summary }));
+    }
+    else {
+        console.log("Dry run: no files were modified.");
+        console.log(`Would update @story and @supports annotations from '${from}' to '${to}' under ${root}.`);
+        console.log(`Estimated stale annotations before update: ${summary.estimatedStaleCount}.`);
+    }
+    return exports.EXIT_OK;
+}
 /**
  * Handle the `update` subcommand to rewrite story annotation references.
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
@@ -126,32 +153,28 @@ function handleUpdate(normalized) {
     const from = flags.from;
     const to = flags.to;
     if (flags.dryRun) {
-        // For now, we cannot get a per-file diff without changing the maintenance API.
-        // We conservatively reuse generateMaintenanceReport to indicate potential impact.
-        const beforeReport = (0, report_1.generateMaintenanceReport)(root, options);
-        const potentialChanges = beforeReport ? beforeReport.split("\n").length : 0;
-        const summary = {
+        return handleUpdateDryRun(root, from, to, {
+            ignorePatterns: flags.ignorePatterns,
+            json: flags.json,
+        });
+    }
+    const result = (0, update_1.updateAnnotationReferences)(root, from, to, options);
+    // Report malformed annotations if any were found
+    if (result.warnings.length > 0) {
+        console.error("\nWarnings - malformed annotations detected:");
+        result.warnings.forEach((warning) => console.error(`  ${warning}`));
+    }
+    if (flags.json) {
+        console.log(JSON.stringify({
             root,
             from,
             to,
-            estimatedStaleCount: potentialChanges,
-        };
-        if (flags.json) {
-            console.log(JSON.stringify({ mode: "dry-run", ...summary }));
-        }
-        else {
-            console.log("Dry run: no files were modified.");
-            console.log(`Would update @story annotations from '${from}' to '${to}' under ${root}.`);
-            console.log(`Estimated stale annotations before update: ${summary.estimatedStaleCount}.`);
-        }
-        return exports.EXIT_OK;
-    }
-    const count = (0, update_1.updateAnnotationReferences)(root, from, to, options);
-    if (flags.json) {
-        console.log(JSON.stringify({ root, from, to, updated: count }));
+            updated: result.count,
+            warnings: result.warnings,
+        }));
     }
     else {
-        console.log(`Updated ${count} @story annotation${count === 1 ? "" : "s"} from '${from}' to '${to}' under ${root}.`);
+        console.log(`Updated ${result.count} annotation${result.count === 1 ? "" : "s"} (@story and @supports) from '${from}' to '${to}' under ${root}.`);
     }
     return exports.EXIT_OK;
 }

package/lib/maintenance/update.d.ts

@@ -2,11 +2,15 @@ import { GetAllFilesOptions } from "./utils";
 /**
  * Update annotation references when story files are moved or renamed
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-UPDATE - Update annotation references
+ * @req REQ-MAINT-UPDATE
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE
  * @param codebasePath Absolute or workspace-root path whose files will be updated in-place.
- * @param oldPath The original @story path to search for in annotation comments.
- * @param newPath The replacement @story path that will replace occurrences of oldPath.
+ * @param oldPath The original path to search for in annotations.
+ * @param newPath The replacement path.
  * @param options Optional configuration including ESLint ignore patterns
- * @returns The number of @story annotations that were updated across the codebase.
+ * @returns Object with count of annotations updated and array of warnings
  */
-export declare function updateAnnotationReferences(codebasePath: string, oldPath: string, newPath: string, options?: GetAllFilesOptions): number;
+export declare function updateAnnotationReferences(codebasePath: string, oldPath: string, newPath: string, options?: GetAllFilesOptions): {
+    count: number;
+    warnings: string[];
+};

package/lib/maintenance/update.js

@@ -36,29 +36,60 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.updateAnnotationReferences = updateAnnotationReferences;
 const fs = __importStar(require("fs"));
 const utils_1 = require("./utils");
+/**
+ * Detect malformed annotations in file content
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-UPDATE - Detect and report malformed annotations
+ */
+function detectMalformedAnnotations(content, filePath) {
+    const warnings = [];
+    const lines = content.split("\n");
+    lines.forEach((line, idx) => {
+        const lineNum = idx + 1;
+        /* eslint-disable traceability/valid-annotation-format */
+        // Detect @story without a path
+        if (/@story\s*$/.test(line.trim()) || /@story\s*\*\//.test(line)) {
+            warnings.push(`${filePath}:${lineNum}: @story annotation without path`);
+        }
+        // Detect @supports without a path or requirements
+        if (/@supports\s*$/.test(line.trim()) || /@supports\s*\*\//.test(line)) {
+            warnings.push(`${filePath}:${lineNum}: @supports annotation without path/requirements`);
+        }
+        // Detect @req without a requirement ID
+        if (/@req\s*$/.test(line.trim()) ||
+            /@req\s*\*\//.test(line) ||
+            /@req\s+-\s/.test(line)) {
+            warnings.push(`${filePath}:${lineNum}: @req annotation without requirement ID`);
+        }
+        /* eslint-enable traceability/valid-annotation-format */
+    });
+    return warnings;
+}
 /**
  * Helper to process a single file for annotation reference updates
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UPDATE
  * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE
  */
-function processFileForAnnotationUpdates(fullPath, regex, newPath, replacementCountRef) {
-    const content = fs.readFileSync(fullPath, "utf8"); // getAllFiles already returns regular files
-    const newContent = content.replace(regex, 
-    /**
-     * Replacement callback to update annotation references
-     * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-     * @req REQ-MAINT-UPDATE
-     */
-    (match, p1) => {
-        replacementCountRef.count++;
+function processFileForAnnotationUpdates(fullPath, regexes, newPath, refs) {
+    const content = fs.readFileSync(fullPath, "utf8");
+    // Detect malformed annotations before processing
+    const malformedWarnings = detectMalformedAnnotations(content, fullPath);
+    refs.warnings.push(...malformedWarnings);
+    let newContent = content;
+    /* eslint-disable traceability/valid-annotation-format */
+    // Update @story references
+    newContent = newContent.replace(regexes.story, (match, p1) => {
+        refs.count++;
         return `${p1}${newPath}`;
     });
-    /**
-     * Write file only if content changed
-     * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-     * @req REQ-MAINT-UPDATE
-     */
+    // Update @supports references
+    newContent = newContent.replace(regexes.supports, (match, prefix, suffix) => {
+        refs.count++;
+        return `${prefix}${newPath}${suffix}`;
+    });
+    /* eslint-enable traceability/valid-annotation-format */
+    // Write file only if content changed
     if (newContent !== content) {
         fs.writeFileSync(fullPath, newContent, "utf8");
     }
@@ -66,43 +97,32 @@ function processFileForAnnotationUpdates(fullPath, regex, newPath, replacementCo
 /**
  * Update annotation references when story files are moved or renamed
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-UPDATE - Update annotation references
+ * @req REQ-MAINT-UPDATE
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE
  * @param codebasePath Absolute or workspace-root path whose files will be updated in-place.
- * @param oldPath The original @story path to search for in annotation comments.
- * @param newPath The replacement @story path that will replace occurrences of oldPath.
+ * @param oldPath The original path to search for in annotations.
+ * @param newPath The replacement path.
  * @param options Optional configuration including ESLint ignore patterns
- * @returns The number of @story annotations that were updated across the codebase.
+ * @returns Object with count of annotations updated and array of warnings
  */
 function updateAnnotationReferences(codebasePath, oldPath, newPath, options) {
-    /**
-     * Check that the provided codebase path exists and is a directory.
-     * If not, abort early.
-     * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-     * @req REQ-MAINT-UPDATE
-     */
+    // Check that the provided codebase path exists and is a directory.
     // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE
     if (!fs.existsSync(codebasePath) ||
         !fs.statSync(codebasePath).isDirectory()) {
-        return 0;
+        return { count: 0, warnings: [] };
     }
-    const replacementCountRef = { count: 0 };
+    const refs = { count: 0, warnings: [] };
     const escapedOldPath = oldPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const regex = new RegExp(`(@story\\s*)${escapedOldPath}`, "g");
+    // Create regex patterns for both story and supports references
+    const storyRegex = new RegExp(`(@story\\s*)${escapedOldPath}`, "g");
+    // Match supports with old path, capturing prefix and suffix requirements
+    const supportsRegex = new RegExp(`(@supports\\s+)${escapedOldPath}(\\s+[A-Z][A-Z0-9_-]*(?:#\\d+)?(?:\\s+[A-Z][A-Z0-9_-]*(?:#\\d+)?)*)`, "g");
     const files = (0, utils_1.getAllFiles)(codebasePath, options);
-    /**
-     * Iterate over all files and replace annotation references
-     * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-     * @req REQ-MAINT-UPDATE
-     * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE
-     */
-    /**
-     * Loop over each discovered file path
-     * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-     * @req REQ-MAINT-UPDATE
-     * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE
-     */
+    // Loop over each discovered file path
+    // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE
     for (const fullPath of files) {
-        processFileForAnnotationUpdates(fullPath, regex, newPath, replacementCountRef);
+        processFileForAnnotationUpdates(fullPath, { story: storyRegex, supports: supportsRegex }, newPath, refs);
     }
-    return replacementCountRef.count;
+    return { count: refs.count, warnings: refs.warnings };
 }

package/lib/rules/helpers/valid-annotation-options.d.ts

@@ -43,6 +43,13 @@ export interface AnnotationRuleOptions {
      * Human-readable example requirement ID used in error messages.
      */
     requirementIdExample?: string;
+    /**
+     * Story directories to validate against. When provided, derives storyPathPattern
+     * to match files within these directories if no explicit pattern is configured.
+     * Aligns with valid-story-reference configuration.
+     * Default: ["docs/stories", "stories"]
+     */
+    storyDirectories?: string[];
     /**
      * Global toggle for auto-fix behavior in valid-annotation-format.
      * When false, no automatic suffix-normalization fixes are applied.
@@ -140,6 +147,12 @@ export declare function getRuleSchema(): {
         requirementIdExample: {
             type: string;
         };
+        storyDirectories: {
+            type: string;
+            items: {
+                type: string;
+            };
+        };
         autoFix: {
             type: string;
         };

package/lib/rules/helpers/valid-annotation-options.js

@@ -16,6 +16,29 @@ exports.getRuleSchema = getRuleSchema;
  * @req REQ-SCHEMA-VALIDATION - Use JSON Schema to validate configuration options
  */
 const pattern_validators_1 = require("./pattern-validators");
+/**
+ * Derive a story path pattern from configured story directories.
+ * Creates a pattern that matches files within any of the provided directories.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ */
+function deriveStoryPatternFromDirectories(dirs) {
+    // Escape special regex characters in directory paths
+    const escapedDirs = dirs.map((dir) => dir.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+    // Create alternation pattern: (dir1|dir2|...)/filename.story.md
+    const dirsPattern = escapedDirs.length === 1 ? escapedDirs[0] : `(${escapedDirs.join("|")})`;
+    return new RegExp(String.raw `^${dirsPattern}/[0-9]+\.[0-9]+-DEV-[\w-]+\.story\.md$`);
+}
+/**
+ * Derive a story path example from configured story directories.
+ * Uses the first directory in the list to create an example path.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ */
+function deriveStoryExampleFromDirectories(dirs) {
+    const firstDir = dirs[0] || "docs/stories";
+    return `${firstDir}/005.0-DEV-EXAMPLE.story.md`;
+}
 /**
  * Get the default regular expression used to validate story paths.
  *
@@ -98,21 +121,31 @@ function getOptionErrors() {
 /**
  * Resolve the story path pattern from nested or flat configuration
  * fields, validating and falling back to the default as needed.
+ * If storyDirectories is provided but no explicit pattern, derives pattern from directories.
  *
  * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
  * @req REQ-PATTERN-CONFIG - Allow configurable story path patterns
  * @req REQ-REGEX-VALIDATION - Validate story path regex options
  * @req REQ-BACKWARD-COMPAT - Use a default when no pattern is provided
  */
-function resolveStoryPattern(nestedStoryPattern, flatStoryPattern) {
-    return (0, pattern_validators_1.resolvePattern)({
-        nestedPattern: nestedStoryPattern,
-        nestedFieldName: "story.pattern",
-        flatPattern: flatStoryPattern,
-        flatFieldName: "storyPathPattern",
-        defaultPattern: getDefaultStoryPattern(),
-        errors: optionErrors,
-    });
+function resolveStoryPattern(nestedStoryPattern, flatStoryPattern, storyDirectories) {
+    // If an explicit pattern is provided (nested or flat), use it
+    if (nestedStoryPattern || flatStoryPattern) {
+        return (0, pattern_validators_1.resolvePattern)({
+            nestedPattern: nestedStoryPattern,
+            nestedFieldName: "story.pattern",
+            flatPattern: flatStoryPattern,
+            flatFieldName: "storyPathPattern",
+            defaultPattern: getDefaultStoryPattern(),
+            errors: optionErrors,
+        });
+    }
+    // If storyDirectories is provided, derive pattern from it
+    if (storyDirectories && storyDirectories.length > 0) {
+        return deriveStoryPatternFromDirectories(storyDirectories);
+    }
+    // Otherwise, use the default pattern
+    return getDefaultStoryPattern();
 }
 /**
  * Resolve the requirement ID pattern from nested or flat configuration
@@ -141,8 +174,17 @@ function resolveReqPattern(nestedReqPattern, flatReqPattern) {
  * @req REQ-EXAMPLE-MESSAGES - Allow custom story examples in messages
  * @req REQ-BACKWARD-COMPAT - Use a default story example when omitted
  */
-function resolveStoryExample(nestedStoryExample, flatStoryExample) {
-    return (0, pattern_validators_1.resolveExample)(nestedStoryExample, flatStoryExample, getDefaultStoryExample());
+function resolveStoryExample(nestedStoryExample, flatStoryExample, storyDirectories) {
+    // If an explicit example is provided, use it
+    if (nestedStoryExample || flatStoryExample) {
+        return (0, pattern_validators_1.resolveExample)(nestedStoryExample, flatStoryExample, getDefaultStoryExample());
+    }
+    // If storyDirectories is provided, derive example from it
+    if (storyDirectories && storyDirectories.length > 0) {
+        return deriveStoryExampleFromDirectories(storyDirectories);
+    }
+    // Otherwise, use the default example
+    return getDefaultStoryExample();
 }
 /**
  * Resolve the requirement ID example string from nested or flat configuration
@@ -227,9 +269,9 @@ function resolveOptionsInternal(user) {
     const { nestedReqExample, flatReqExample } = getReqExampleInputs(user);
     const autoFixFlag = user?.autoFix;
     const autoFix = typeof autoFixFlag === "boolean" ? autoFixFlag : true;
-    const storyPattern = resolveStoryPattern(nestedStoryPattern, flatStoryPattern);
+    const storyPattern = resolveStoryPattern(nestedStoryPattern, flatStoryPattern, user?.storyDirectories);
     const reqPattern = resolveReqPattern(nestedReqPattern, flatReqPattern);
-    const storyExample = resolveStoryExample(nestedStoryExample, flatStoryExample);
+    const storyExample = resolveStoryExample(nestedStoryExample, flatStoryExample, user?.storyDirectories);
     const reqExample = resolveReqExample(nestedReqExample, flatReqExample);
     return {
         storyPattern,
@@ -290,6 +332,7 @@ function getRuleSchema() {
                 storyPathExample: { type: "string" },
                 requirementIdPattern: { type: "string" },
                 requirementIdExample: { type: "string" },
+                storyDirectories: { type: "array", items: { type: "string" } },
                 autoFix: { type: "boolean" },
             },
             additionalProperties: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.25.0",
+  "version": "1.27.0",
   "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/index.js",
   "types": "lib/index.d.ts",
@@ -28,8 +28,9 @@
     "lint:require-built-plugin": "npm run lint-plugin-guard",
     "lint": "eslint --config eslint.config.js \"src/**/*.{js,ts}\" \"tests/**/*.{js,ts}\" --max-warnings=0",
     "test": "jest --ci --bail",
-    "test:unit": "jest --ci --bail --testPathPatterns='tests/(rules|maintenance|utils|unit)' --testPathIgnorePatterns='integration'",
+    "test:unit": "jest --ci --bail --testPathPatterns='tests/(rules|maintenance|utils|unit)' --testPathIgnorePatterns='integration|e2e'",
     "test:integration": "jest --ci --bail --testPathPatterns='tests/integration'",
+    "test:e2e": "jest --ci --bail --testPathPatterns='tests/e2e'",
     "ci-verify": "npm run type-check && npm run lint && npm run format:check && npm run duplication && npm run check:traceability && npm test && npm run audit:ci && npm run safety:deps",
     "ci-verify:full": "npm run check:traceability && npm run safety:deps && npm run audit:ci && npm run build && npm run smoke:runtime && npm run type-check && npm run lint-plugin-check && npm run lint -- --max-warnings=0 && npm run duplication && npm run test -- --coverage && npm run format:check && npm audit --omit=dev --audit-level=high && npm run audit:dev-high && npm run check:ci-artifacts",
     "ci-verify:fast": "npm run type-check && npm run check:traceability && npm run duplication && jest --ci --bail --passWithNoTests --testPathPatterns 'tests/(rules|maintenance)'",

package/user-docs/api-reference.md

@@ -551,7 +551,11 @@ export default [js.configs.recommended, traceability.configs.strict];
 
 ## Maintenance API and CLI
 
-The plugin exposes a small maintenance API and a companion CLI, `traceability-maint`, for bulk operations on `@story` annotations. These tools are intentionally minimal and focused on stale **story** references only; requirement-level maintenance and more advanced filtering are planned but **not yet implemented**. All maintenance functions operate only on the local filesystem under the provided root directory; they do not make any network calls or interact with external services.
+The plugin exposes a maintenance API and CLI, `traceability-maint`, primarily for the **batch update** operation when story files are moved or renamed.
+
+**Note**: The CLI also includes `detect`, `verify`, and `report` commands for historical reasons, but these largely duplicate functionality already provided by ESLint rules (`valid-story-reference`, `valid-req-reference`) during normal linting. The primary value of the maintenance tools is the **update** command, which can perform bulk reference updates across your codebase - something ESLint's auto-fix cannot do.
+
+These tools update both `@story` and `@supports` references when story files are moved or renamed. All maintenance functions operate only on the local filesystem under the provided root directory; they do not make any network calls or interact with external services. These are manual developer tools, not intended for automated pipelines (ESLint rules handle validation during development and builds).
 
 ### Programmatic Maintenance API
 
@@ -603,23 +607,27 @@ Scans the workspace for `@story` annotations that point to missing or out-of-pro
 
 #### `updateAnnotationReferences(rootDir, oldPath, newPath)`
 
-Performs a targeted text replacement of `@story` values across the workspace.
+Performs a targeted text replacement of `@story` and `@supports` values across the workspace, and detects malformed annotations.
 
 **Parameters:**
 
 - `rootDir` (string, required) – Workspace root to update in-place.
-- `oldPath` (string, required) – The story path to search for after `@story`.
+- `oldPath` (string, required) – The story path to search for in `@story` and `@supports` annotations.
 - `newPath` (string, required) – The replacement story path.
 
 **Returns:**
 
-- `number` – The count of `@story` annotations that were updated.
+- Object with:
+  - `count` (number) – The count of annotations (`@story` and `@supports`) that were updated.
+  - `warnings` (string[]) – Array of malformed annotation warnings found during processing.
 
 **Behavior notes:**
 
-- Only `@story` annotations are modified; `@req` annotations are never changed.
+- Both `@story` and `@supports` annotations are updated when they reference the old path.
+- For `@supports` annotations, the story path is updated while preserving the requirement IDs.
+- Malformed annotations (missing paths or requirement IDs) are detected and reported in warnings.
 - Files are only written when the content actually changes.
-- If `rootDir` does not exist or is not a directory, the function returns `0` without modifying anything.
+- If `rootDir` does not exist or is not a directory, the function returns `{ count: 0, warnings: [] }`.
 
 #### `batchUpdateAnnotations(rootDir, mappings)`
 
@@ -632,12 +640,14 @@ Runs multiple `updateAnnotationReferences` operations in sequence.
 
 **Returns:**
 
-- `number` – The total number of `@story` annotations updated across all mappings.
+- Object with:
+  - `count` (number) – The total number of annotations updated across all mappings.
+  - `warnings` (string[]) – Combined array of all malformed annotation warnings found.
 
 **Behavior notes:**
 
 - There is no special batching logic; this helper simply loops over the provided mappings.
-- For each mapping, it calls `updateAnnotationReferences(rootDir, oldPath, newPath)` and sums the counts.
+- For each mapping, it calls `updateAnnotationReferences(rootDir, oldPath, newPath)` and aggregates counts and warnings.
 
 #### `verifyAnnotations(rootDir)`
 
@@ -675,9 +685,11 @@ Generates a simple, text-only report of stale `@story` annotations.
 
 ### `traceability-maint` CLI
 
-The `traceability-maint` CLI wraps the maintenance API for use in scripts and CI. It is typically available via `npx traceability-maint` or as an npm script.
+The `traceability-maint` CLI wraps the maintenance API for manual developer invocation when reorganizing story files. It is typically available via `npx traceability-maint`.
+
+**Important**: This CLI is designed for **manual developer execution only** when you need to batch-update references after moving or renaming story files. It should **not** be integrated into automated pipelines - ESLint rules (`valid-story-reference`, `valid-req-reference`) already handle validation during development and builds.
 
-These tools are intentionally minimal and focused on stale **story** references only; requirement-level maintenance and more advanced filtering are planned but **not yet implemented**. The CLI currently focuses on stale `@story` annotations only. It does **not** build or consume a separate index file, and it does not yet support requirement-level maintenance.
+The CLI's **primary value** is the `update` command, which performs bulk reference updates that ESLint cannot do. The `detect`, `verify`, and `report` commands are included for historical compatibility but largely duplicate what ESLint already provides during normal linting.
 
 #### General usage
 
@@ -754,7 +766,7 @@ Generates a plain-text or JSON report of stale story references.
 # Human-readable text report (default)
 traceability-maint report --root .
 
-# JSON report suitable for CI
+# Machine-readable JSON output for further analysis
 traceability-maint report --root . --format json
 ```
 
@@ -835,7 +847,7 @@ If `--from` or `--to` is missing, the CLI prints an error, shows the help text,
 }
 ```
 
-In CI:
+Manual verification:
 
 ```bash
 npm run traceability:verify