eslint-plugin-traceability 1.24.0 → 1.26.0

package/CHANGELOG.md

@@ -1,9 +1,14 @@
-# [1.24.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.23.1...v1.24.0) (2026-01-10)
+# [1.26.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.25.0...v1.26.0) (2026-01-11)
+
+
+### Bug Fixes
+
+* **tests:** update performance test for new return types ([6db924f](https://github.com/voder-ai/eslint-plugin-traceability/commit/6db924f7af3c4feadf9528b557a3948a2e89bb19))
 
 
 ### Features
 
-* add auto-fix support to require-traceability rule ([ee35349](https://github.com/voder-ai/eslint-plugin-traceability/commit/ee353492bfbebbc18dba7ae8e4d32b8ec386bdf1))
+* **maintenance:** add [@supports](https://github.com/supports) reference updates and malformed annotation detection ([845a8cf](https://github.com/voder-ai/eslint-plugin-traceability/commit/845a8cf55e5f0444cead557fdea2f9d1b10b588b)), closes [REQ-MAINT-UPDATE#1](https://github.com/REQ-MAINT-UPDATE/issues/1)
 
 # Changelog
 

package/README.md

@@ -292,39 +292,109 @@ 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.
-- `update` – Apply safe, scripted updates to `@story` annotations (e.g., when a story file is renamed).
+### Primary Command
+
+- `update` – Batch update `@story` and `@supports` annotations when a story file is renamed or moved (the key feature ESLint cannot provide)
+
+### Supporting Commands
+
+The CLI also includes `detect`, `verify`, and `report` commands for historical compatibility, but these largely duplicate what ESLint already provides during normal linting:
+
+- `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)
 
 ### Usage
 
-All commands are run from your project root:
+**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 . \
+  --from "stories/old.story.md" \
+  --to "stories/new.story.md" \
+  --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
+# Detect stale story references (ESLint already does this during linting)
 npx traceability-maint detect --root .
 
-# Verify that annotations are valid
+# 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 JSON report for CI pipelines
+# Generate a report (ESLint output already provides this information)
 npx traceability-maint report --root . --format json
+```
 
-# Update references when a story file is renamed
+### Options
+
+- `--root <path>` – Workspace root directory (defaults to current directory)
+- `--json` – Output results in JSON format
+- `--format <text|json>` – Report format (for `report` command)
+- `--from <path>` – Source story path (for `update` command)
+- `--to <path>` – Destination story path (for `update` command)
+- `--dry-run` – Preview changes without modifying files (for `update` command)
+- `--ignore-pattern <pattern>` – Path or directory to ignore (can be specified multiple times)
+
+### ESLint Configuration Integration
+
+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`)
+- Exclude test fixtures or temporary files
+
+Multiple patterns can be specified:
+
+```bash
 npx traceability-maint update \
-  --root . \
-  --from "stories/feature-authentication.story.md" \
-  --to "stories/feature-auth-v2.story.md"
+  --from old.story.md \
+  --to new.story.md \
+  --ignore-pattern node_modules \
+  --ignore-pattern dist \
+  --ignore-pattern coverage
 ```
 
+### 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 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.
 
 ## Plugin Validation

package/lib/maintenance/batch.d.ts

@@ -1,21 +1,30 @@
+import { GetAllFilesOptions } from "./utils";
 /**
  * Batch update annotations and verify references
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @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.
- * @returns Total number of updated @story annotations across all mappings.
+ * @param options Optional configuration including ESLint ignore patterns
+ * @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;
-}[]): 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
  * @req REQ-MAINT-VERIFY - Verify annotation references
+ * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
  * @param codebasePath Absolute path to the workspace root whose annotations should be verified.
+ * @param options Optional configuration including ESLint ignore patterns
  * @returns Boolean indicating whether there are no stale annotations remaining (true if clean, false if any remain).
  */
-export declare function verifyAnnotations(codebasePath: string): boolean;
+export declare function verifyAnnotations(codebasePath: string, options?: GetAllFilesOptions): boolean;

package/lib/maintenance/batch.js

@@ -9,25 +9,33 @@ const detect_1 = require("./detect");
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @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.
- * @returns Total number of updated @story annotations across all mappings.
+ * @param options Optional configuration including ESLint ignore patterns
+ * @returns Object with total count of updated annotations and array of malformed annotation warnings
  */
-function batchUpdateAnnotations(codebasePath, mappings) {
+function batchUpdateAnnotations(codebasePath, mappings, options) {
     let totalUpdated = 0;
+    const allWarnings = [];
     for (const { oldPath, newPath } of mappings) {
-        totalUpdated += (0, update_1.updateAnnotationReferences)(codebasePath, oldPath, newPath);
+        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
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-VERIFY - Verify annotation references
+ * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
  * @param codebasePath Absolute path to the workspace root whose annotations should be verified.
+ * @param options Optional configuration including ESLint ignore patterns
  * @returns Boolean indicating whether there are no stale annotations remaining (true if clean, false if any remain).
  */
-function verifyAnnotations(codebasePath) {
-    const staleAnnotations = (0, detect_1.detectStaleAnnotations)(codebasePath);
+function verifyAnnotations(codebasePath, options) {
+    const staleAnnotations = (0, detect_1.detectStaleAnnotations)(codebasePath, options);
     return staleAnnotations.length === 0;
 }

package/lib/maintenance/commands.d.ts

@@ -7,6 +7,7 @@ export declare const EXIT_USAGE = 2;
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-DETECT - CLI surface for detection of stale annotations
  * @req REQ-MAINT-SAFE - Return specific exit codes for stale vs clean states
+ * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
  * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-SAFE
  */
 export declare function handleDetect(normalized: NormalizedCliArgs): number;
@@ -15,6 +16,7 @@ export declare function handleDetect(normalized: NormalizedCliArgs): number;
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-VERIFY - CLI surface for verification of annotations
  * @req REQ-MAINT-SAFE - Return distinct exit codes for verification failures
+ * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
  * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-VERIFY REQ-MAINT-SAFE
  */
 export declare function handleVerify(normalized: NormalizedCliArgs): number;
@@ -23,6 +25,7 @@ export declare function handleVerify(normalized: NormalizedCliArgs): number;
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-REPORT - CLI surface for human-readable maintenance reports
  * @req REQ-MAINT-SAFE - Support machine-readable formats for safe automation
+ * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
  * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-REPORT REQ-MAINT-SAFE
  */
 export declare function handleReport(normalized: NormalizedCliArgs): number;

package/lib/maintenance/commands.js

@@ -28,12 +28,16 @@ exports.EXIT_USAGE = 2;
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-DETECT - CLI surface for detection of stale annotations
  * @req REQ-MAINT-SAFE - Return specific exit codes for stale vs clean states
+ * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
  * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-SAFE
  */
 function handleDetect(normalized) {
     const flags = (0, flags_1.parseFlags)(normalized);
     const root = flags.root;
-    const stale = (0, detect_1.detectStaleAnnotations)(root);
+    const options = flags.ignorePatterns
+        ? { ignorePatterns: flags.ignorePatterns }
+        : undefined;
+    const stale = (0, detect_1.detectStaleAnnotations)(root, options);
     if (flags.json) {
         // Emit JSON output to support consumption by external tools and scripts.
         console.log(JSON.stringify({ root, stale }));
@@ -55,12 +59,16 @@ Run 'traceability-maint report' for a structured summary.`);
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-VERIFY - CLI surface for verification of annotations
  * @req REQ-MAINT-SAFE - Return distinct exit codes for verification failures
+ * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
  * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-VERIFY REQ-MAINT-SAFE
  */
 function handleVerify(normalized) {
     const flags = (0, flags_1.parseFlags)(normalized);
     const root = flags.root;
-    const valid = (0, batch_1.verifyAnnotations)(root);
+    const options = flags.ignorePatterns
+        ? { ignorePatterns: flags.ignorePatterns }
+        : undefined;
+    const valid = (0, batch_1.verifyAnnotations)(root, options);
     if (valid) {
         console.log(`All traceability annotations under ${root} are valid.`);
         return exports.EXIT_OK;
@@ -73,13 +81,17 @@ function handleVerify(normalized) {
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-REPORT - CLI surface for human-readable maintenance reports
  * @req REQ-MAINT-SAFE - Support machine-readable formats for safe automation
+ * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
  * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-REPORT REQ-MAINT-SAFE
  */
 function handleReport(normalized) {
     const flags = (0, flags_1.parseFlags)(normalized);
     const root = flags.root;
     const format = flags.format ?? "text";
-    const report = (0, report_1.generateMaintenanceReport)(root);
+    const options = flags.ignorePatterns
+        ? { ignorePatterns: flags.ignorePatterns }
+        : undefined;
+    const report = (0, report_1.generateMaintenanceReport)(root, options);
     if (format === "json") {
         console.log(JSON.stringify({ root, report }));
     }
@@ -94,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
@@ -104,6 +143,9 @@ function handleReport(normalized) {
 function handleUpdate(normalized) {
     const flags = (0, flags_1.parseFlags)(normalized);
     const root = flags.root;
+    const options = flags.ignorePatterns
+        ? { ignorePatterns: flags.ignorePatterns }
+        : undefined;
     if (!flags.from || !flags.to) {
         console.error("'update' requires --from <oldPath> and --to <newPath>.");
         return exports.EXIT_USAGE;
@@ -111,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);
-        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);
-    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/detect.d.ts

@@ -1,8 +1,11 @@
+import { GetAllFilesOptions } from "./utils";
 /**
  * Detect stale annotation references that point to moved or deleted story files
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-DETECT - Detect stale annotation references
+ * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
  * @param codebasePath Path to the codebase root, treated as a workspace root and resolved against process.cwd().
+ * @param options Optional configuration including ESLint ignore patterns
  * @returns A de-duplicated array of stale @story paths (as strings) whose resolved targets no longer exist on disk.
  */
-export declare function detectStaleAnnotations(codebasePath: string): string[];
+export declare function detectStaleAnnotations(codebasePath: string, options?: GetAllFilesOptions): string[];

package/lib/maintenance/detect.js

@@ -42,10 +42,12 @@ const storyReferenceUtils_1 = require("../utils/storyReferenceUtils");
  * Detect stale annotation references that point to moved or deleted story files
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-DETECT - Detect stale annotation references
+ * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
  * @param codebasePath Path to the codebase root, treated as a workspace root and resolved against process.cwd().
+ * @param options Optional configuration including ESLint ignore patterns
  * @returns A de-duplicated array of stale @story paths (as strings) whose resolved targets no longer exist on disk.
  */
-function detectStaleAnnotations(codebasePath) {
+function detectStaleAnnotations(codebasePath, options) {
     const cwd = process.cwd();
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
     // @req REQ-MAINT-DETECT - Treat codebasePath as a workspace root resolved from process.cwd()
@@ -62,7 +64,8 @@ function detectStaleAnnotations(codebasePath) {
     const stale = new Set();
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
     // @req REQ-MAINT-DETECT - Iterate over all files in the isolated workspace root
-    const files = (0, utils_1.getAllFiles)(workspaceRoot);
+    // @req REQ-MAINT-UPDATE - Apply ESLint ignore patterns during file discovery
+    const files = (0, utils_1.getAllFiles)(workspaceRoot, options);
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
     // @req REQ-MAINT-DETECT - Loop over each workspace file to inspect its @story annotations
     for (const file of files) {

package/lib/maintenance/flags.d.ts

@@ -83,6 +83,7 @@ export interface ParsedFlags {
     from?: string;
     to?: string;
     dryRun?: boolean;
+    ignorePatterns?: string[];
 }
 /**
  * Basic flag parser for maintenance CLI subcommands.

package/lib/maintenance/flags.js

@@ -152,6 +152,22 @@ function handleDryRunFlag(flags, args, index) {
     flags.dryRun = true;
     return index;
 }
+/**
+ * Handle the --ignore-pattern flag, collecting ignore patterns for ESLint integration
+ *
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-UPDATE - Support ESLint configuration integration
+ */
+function handleIgnorePatternFlag(flags, args, index) {
+    if (args[index] !== "--ignore-pattern" || !isNextValueString(args, index)) {
+        return index;
+    }
+    if (!flags.ignorePatterns) {
+        flags.ignorePatterns = [];
+    }
+    flags.ignorePatterns.push(args[index + 1]);
+    return index + 1;
+}
 /**
  * Handle a single CLI argument and update the flags accordingly.
  *
@@ -183,6 +199,10 @@ function applyFlag(flags, args, index) {
     if (afterDryRun !== index) {
         return afterDryRun;
     }
+    const afterIgnorePattern = handleIgnorePatternFlag(flags, args, index);
+    if (afterIgnorePattern !== index) {
+        return afterIgnorePattern;
+    }
     return index;
 }
 /**

package/lib/maintenance/report.d.ts

@@ -1,9 +1,11 @@
+import { GetAllFilesOptions } from "./utils";
 /**
  * Generate a report of maintenance operations performed
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-REPORT - Generate maintenance report
  * @req REQ-MAINT-SAFE - Ensure operations are safe and reversible
  * @param codebasePath The workspace root to scan for stale maintenance annotations.
+ * @param options Optional configuration including ESLint ignore patterns
  * @returns An empty string when no stale annotations are found, or a newline-separated list of stale `@story` paths.
  */
-export declare function generateMaintenanceReport(codebasePath: string): string;
+export declare function generateMaintenanceReport(codebasePath: string, options?: GetAllFilesOptions): string;

package/lib/maintenance/report.js

@@ -1,21 +1,182 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateMaintenanceReport = generateMaintenanceReport;
 const detect_1 = require("./detect");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Detect circular references in story annotations
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-REPORT - Handle circular reference edge cases
+ * @param codebasePath The workspace root to scan for circular references
+ * @returns Array of circular reference chains detected
+ */
+function detectCircularReferences(codebasePath) {
+    const circularChains = [];
+    const storyGraph = new Map();
+    // Build a graph of story file references
+    try {
+        buildStoryGraph(codebasePath, storyGraph);
+        // Detect cycles using DFS
+        const visited = new Set();
+        const recursionStack = new Set();
+        for (const storyPath of storyGraph.keys()) {
+            if (!visited.has(storyPath)) {
+                detectCycles(storyPath, {
+                    graph: storyGraph,
+                    visited,
+                    recursionStack,
+                    path: [],
+                    circularChains,
+                });
+            }
+        }
+    }
+    catch {
+        // Silently handle errors during circular reference detection
+        // to avoid breaking the main report generation
+    }
+    return circularChains;
+}
+/**
+ * Build a graph of story file cross-references
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-REPORT - Build dependency graph for circular detection
+ */
+function buildStoryGraph(codebasePath, graph) {
+    const storyFiles = findStoryFiles(codebasePath);
+    for (const storyFile of storyFiles) {
+        const content = fs.readFileSync(storyFile, "utf8");
+        const references = extractStoryReferences(content);
+        const relativePath = path.relative(codebasePath, storyFile);
+        if (!graph.has(relativePath)) {
+            graph.set(relativePath, new Set());
+        }
+        for (const ref of references) {
+            graph.get(relativePath)?.add(ref);
+        }
+    }
+}
+/**
+ * Find all story files in the codebase
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-REPORT - Locate story files for circular detection
+ */
+function findStoryFiles(dir) {
+    const storyFiles = [];
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+        return storyFiles;
+    }
+    const entries = fs.readdirSync(dir);
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry);
+        const stat = fs.statSync(fullPath);
+        if (stat.isDirectory()) {
+            storyFiles.push(...findStoryFiles(fullPath));
+        }
+        else if (stat.isFile() && entry.endsWith(".story.md")) {
+            storyFiles.push(fullPath);
+        }
+    }
+    return storyFiles;
+}
+/**
+ * Extract story references from file content
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-REPORT - Parse story references for circular detection
+ */
+function extractStoryReferences(content) {
+    const references = [];
+    const storyPattern = /@story\s+([^\s]+\.story\.md)/g;
+    let match;
+    while ((match = storyPattern.exec(content)) !== null) {
+        references.push(match[1]);
+    }
+    return references;
+}
+/**
+ * Detect cycles in the story dependency graph using DFS
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-REPORT - Detect circular dependencies using graph traversal
+ */
+function detectCycles(node, options) {
+    const { graph, visited, recursionStack, path, circularChains } = options;
+    visited.add(node);
+    recursionStack.add(node);
+    path.push(node);
+    const neighbors = graph.get(node) || new Set();
+    for (const neighbor of neighbors) {
+        if (!visited.has(neighbor)) {
+            detectCycles(neighbor, options);
+        }
+        else if (recursionStack.has(neighbor)) {
+            // Found a cycle
+            const cycleStart = path.indexOf(neighbor);
+            const cycle = path.slice(cycleStart).concat(neighbor);
+            circularChains.push(`Circular reference: ${cycle.join(" -> ")}`);
+        }
+    }
+    path.pop();
+    recursionStack.delete(node);
+}
 /**
  * Generate a report of maintenance operations performed
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-REPORT - Generate maintenance report
  * @req REQ-MAINT-SAFE - Ensure operations are safe and reversible
  * @param codebasePath The workspace root to scan for stale maintenance annotations.
+ * @param options Optional configuration including ESLint ignore patterns
  * @returns An empty string when no stale annotations are found, or a newline-separated list of stale `@story` paths.
  */
-function generateMaintenanceReport(codebasePath) {
-    const staleAnnotations = (0, detect_1.detectStaleAnnotations)(codebasePath);
+function generateMaintenanceReport(codebasePath, options) {
+    const staleAnnotations = (0, detect_1.detectStaleAnnotations)(codebasePath, options);
+    const circularReferences = detectCircularReferences(codebasePath);
+    const reportSections = [];
     // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
     // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-REPORT
-    if (staleAnnotations.length === 0) {
-        return "";
+    if (staleAnnotations.length > 0) {
+        reportSections.push("Stale Annotations:");
+        reportSections.push(...staleAnnotations);
+    }
+    if (circularReferences.length > 0) {
+        if (reportSections.length > 0) {
+            reportSections.push("");
+        }
+        reportSections.push("Circular References:");
+        reportSections.push(...circularReferences);
     }
-    return staleAnnotations.join("\n");
+    return reportSections.join("\n");
 }

package/lib/maintenance/update.d.ts

@@ -1,10 +1,16 @@
+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.
- * @returns The number of @story annotations that were updated across the codebase.
+ * @param oldPath The original path to search for in annotations.
+ * @param newPath The replacement path.
+ * @param options Optional configuration including ESLint ignore patterns
+ * @returns Object with count of annotations updated and array of warnings
  */
-export declare function updateAnnotationReferences(codebasePath: string, oldPath: string, newPath: string): 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,42 +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.
- * @returns The number of @story annotations that were updated across the codebase.
+ * @param oldPath The original path to search for in annotations.
+ * @param newPath The replacement path.
+ * @param options Optional configuration including ESLint ignore patterns
+ * @returns Object with count of annotations updated and array of warnings
  */
-function updateAnnotationReferences(codebasePath, oldPath, newPath) {
-    /**
-     * 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
-     */
+function updateAnnotationReferences(codebasePath, oldPath, newPath, options) {
+    // 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");
-    const files = (0, utils_1.getAllFiles)(codebasePath);
-    /**
-     * 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
-     */
+    // 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);
+    // 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/maintenance/utils.d.ts

@@ -1,6 +1,23 @@
+/**
+ * Options for file traversal with optional ignore patterns
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-UPDATE - Support ESLint configuration integration
+ */
+export interface GetAllFilesOptions {
+    /**
+     * Array of glob patterns or absolute paths to ignore during traversal.
+     * Supports both directory paths (to skip entire directories) and file patterns.
+     * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+     * @req REQ-MAINT-UPDATE - Respect ESLint ignore patterns
+     */
+    ignorePatterns?: string[];
+}
 /**
  * Recursively retrieve all files in a directory.
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UTILS - Extract common file traversal logic for maintenance tools
+ * @req REQ-MAINT-UPDATE - Support ESLint configuration integration
+ * @param dir Root directory to scan
+ * @param options Optional configuration including ignore patterns from ESLint config
  */
-export declare function getAllFiles(dir: string): string[];
+export declare function getAllFiles(dir: string, options?: GetAllFilesOptions): string[];

package/lib/maintenance/utils.js

@@ -40,9 +40,13 @@ const path = __importStar(require("path"));
  * Recursively retrieve all files in a directory.
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UTILS - Extract common file traversal logic for maintenance tools
+ * @req REQ-MAINT-UPDATE - Support ESLint configuration integration
+ * @param dir Root directory to scan
+ * @param options Optional configuration including ignore patterns from ESLint config
  */
-function getAllFiles(dir) {
+function getAllFiles(dir, options) {
     const fileList = [];
+    const ignorePatterns = options?.ignorePatterns ?? [];
     /**
      * Ensure the provided path exists and is a directory before traversal.
      * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
@@ -56,15 +60,34 @@ function getAllFiles(dir) {
     if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
         return fileList;
     }
-    traverseDirectory(dir, fileList);
+    traverseDirectory(dir, fileList, ignorePatterns);
     return fileList;
 }
+/**
+ * Check if a path should be ignored based on patterns
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-UPDATE - Respect ESLint ignore patterns
+ */
+function shouldIgnore(filePath, ignorePatterns) {
+    for (const pattern of ignorePatterns) {
+        // Support both exact path matches and directory prefix matches
+        if (filePath === pattern ||
+            filePath.startsWith(pattern + path.sep) ||
+            // Support common patterns like node_modules, dist, etc.
+            filePath.includes(path.sep + pattern + path.sep) ||
+            filePath.endsWith(path.sep + pattern)) {
+            return true;
+        }
+    }
+    return false;
+}
 /**
  * Recursively traverse a directory and collect file paths.
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UTILS-TRAVERSE - Helper traversal function used by getAllFiles
+ * @req REQ-MAINT-UPDATE - Apply ignore patterns during traversal
  */
-function traverseDirectory(currentDir, fileList) {
+function traverseDirectory(currentDir, fileList, ignorePatterns) {
     const entries = fs.readdirSync(currentDir);
     /**
      * Iterate over directory entries using a for-of loop.
@@ -73,6 +96,14 @@ function traverseDirectory(currentDir, fileList) {
      */
     for (const entry of entries) {
         const fullPath = path.join(currentDir, entry);
+        /**
+         * Skip ignored paths based on ESLint configuration
+         * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+         * @req REQ-MAINT-UPDATE - Respect ESLint ignore patterns
+         */
+        if (shouldIgnore(fullPath, ignorePatterns)) {
+            continue;
+        }
         const stat = fs.statSync(fullPath);
         /**
          * Recurse into directories to continue traversal.
@@ -80,7 +111,7 @@ function traverseDirectory(currentDir, fileList) {
          * @req REQ-MAINT-UTILS-TRAVERSE-DIR - Handle directory entries during traversal
          */
         if (stat.isDirectory()) {
-            traverseDirectory(fullPath, fileList);
+            traverseDirectory(fullPath, fileList, ignorePatterns);
             /**
              * Collect regular file entries during traversal.
              * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md

package/package.json

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

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