eslint-plugin-traceability 1.31.2 → 1.31.4

package/CHANGELOG.md

@@ -1,9 +1,10 @@
-## [1.31.2](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.31.1...v1.31.2) (2026-01-14)
+## [1.31.4](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.31.3...v1.31.4) (2026-01-14)
 
 
 ### Bug Fixes
 
-* **rules:** add [@supports](https://github.com/supports) validation to valid-story-reference rule ([f30798b](https://github.com/voder-ai/eslint-plugin-traceability/commit/f30798b9437428b69e5553d75366e6cfd8d9eb99))
+* **rules:** remove fake REQ-CREATE-HOOK from require-req-annotation.ts ([e8627a3](https://github.com/voder-ai/eslint-plugin-traceability/commit/e8627a35ae45a1e2089ca6fc0c392181726b6ec7))
+* **src:** remove fake requirement IDs and convert to [@supports](https://github.com/supports) format in index.ts ([51fffcd](https://github.com/voder-ai/eslint-plugin-traceability/commit/51fffcda86df82e89f4bff97886ef76d1aa39b09))
 
 # Changelog
 

package/lib/index.d.ts

@@ -5,10 +5,6 @@
  * @req REQ-ERROR-HANDLING - Gracefully handles plugin loading errors and missing dependencies
  */
 import type { Rule } from "eslint";
-/**
- * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINTENANCE-API-EXPORT - Expose maintenance utilities alongside core plugin exports
- */
 import { detectStaleAnnotations, updateAnnotationReferences, batchUpdateAnnotations, verifyAnnotations, generateMaintenanceReport } from "./maintenance";
 declare const rules: Record<string, Rule.RuleModule>;
 /**
@@ -45,10 +41,6 @@ declare const configs: {
         };
     }[];
 };
-/**
- * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINTENANCE-API-EXPORT - Expose maintenance utilities alongside core plugin exports
- */
 declare const maintenance: {
     detectStaleAnnotations: typeof detectStaleAnnotations;
     updateAnnotationReferences: typeof updateAnnotationReferences;

package/lib/index.js

@@ -1,15 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.maintenance = exports.configs = exports.rules = void 0;
-/**
- * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINTENANCE-API-EXPORT - Expose maintenance utilities alongside core plugin exports
- */
 const maintenance_1 = require("./maintenance");
-/**
- * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
- * @req REQ-RULE-LIST - Enumerate supported rule file names for plugin discovery
- */
 const RULE_NAMES = [
     "require-traceability",
     "require-story-annotation",
@@ -24,22 +16,8 @@ const RULE_NAMES = [
 ];
 const rules = {};
 exports.rules = rules;
-RULE_NAMES.forEach(
-/**
- * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
- * @req REQ-DYNAMIC-LOADING - Support dynamic rule loading by name at runtime
- * @param {RuleName} name - Rule file base name used to discover and load rule module
- */
-(name) => {
-    /**
-     * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
-     * @req REQ-DYNAMIC-LOADING - Support dynamic rule loading by name at runtime
-     */
+RULE_NAMES.forEach((name) => {
     try {
-        /**
-         * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
-         * @req REQ-DYNAMIC-LOADING - Support dynamic rule loading by name at runtime
-         */
         // Dynamically require rule module
         const mod = require(`./rules/${name}`);
         // Support ESModule default export
@@ -47,11 +25,7 @@ RULE_NAMES.forEach(
     }
     catch (error) {
         /**
-         * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
-         * @req REQ-ERROR-HANDLING - Provide fallback rule module and surface errors when rule loading fails
-         */
-        /**
-         * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+         * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
          * @req REQ-ERROR-HANDLING - Provide fallback rule module and surface errors when rule loading fails
          */
         console.error(`[eslint-plugin-traceability] Failed to load rule "${name}": ${error.message}`);
@@ -238,12 +212,8 @@ const TRACEABILITY_RULE_SEVERITIES = {
     "traceability/no-redundant-annotation": "warn",
 };
 /**
- * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
- * @req REQ-PLUGIN-STRUCTURE - Provide foundational plugin export and registration
- * @req REQ-ERROR-SEVERITY - Map rule types to appropriate ESLint severity levels (errors vs warnings)
- * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
- * @req REQ-CONFIG-PRESETS - Provide flat-config presets that self-register the plugin and core rules
- *
+ * Create flat config preset for ESLint v9.
+ * @supports docs/stories/001.0-DEV-PLUGIN-SETUP.story.md REQ-PLUGIN-STRUCTURE
  * @supports docs/stories/007.0-DEV-ERROR-REPORTING.story.md REQ-ERROR-SEVERITY
  * @supports docs/stories/002.0-DEV-ESLINT-CONFIG.story.md REQ-CONFIG-PRESETS
  */
@@ -266,10 +236,6 @@ const configs = {
 };
 exports.configs = configs;
 plugin.configs = configs;
-/**
- * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINTENANCE-API-EXPORT - Expose maintenance utilities alongside core plugin exports
- */
 const maintenance = {
     detectStaleAnnotations: maintenance_1.detectStaleAnnotations,
     updateAnnotationReferences: maintenance_1.updateAnnotationReferences,

package/lib/maintenance/batch.d.ts

@@ -3,9 +3,8 @@ 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
+ * @req REQ-MAINT-UPDATE - Update annotation references
+ * @req REQ-MAINT-CLI - Provide CLI command interface
  * @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
@@ -21,8 +20,8 @@ export declare function batchUpdateAnnotations(codebasePath: string, mappings: {
 /**
  * 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
+ * @req REQ-MAINT-CLI - Provide CLI command interface
+ * @req REQ-MAINT-MANUAL-TRIGGER - Manual developer execution
  * @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).

package/lib/maintenance/batch.js

@@ -8,9 +8,8 @@ const detect_1 = require("./detect");
  * 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
+ * @req REQ-MAINT-UPDATE - Update annotation references
+ * @req REQ-MAINT-CLI - Provide CLI command interface
  * @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
@@ -29,8 +28,8 @@ function batchUpdateAnnotations(codebasePath, mappings, options) {
 /**
  * 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
+ * @req REQ-MAINT-CLI - Provide CLI command interface
+ * @req REQ-MAINT-MANUAL-TRIGGER - Manual developer execution
  * @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).

package/lib/maintenance/cli.d.ts

@@ -2,11 +2,9 @@
 /**
  * Maintenance CLI entry point.
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-DETECT - CLI support for detection of stale annotations
- * @req REQ-MAINT-VERIFY - CLI support for verification of annotations
- * @req REQ-MAINT-REPORT - CLI support for human-readable reports
+ * @req REQ-MAINT-CLI - CLI support for maintenance commands
  * @req REQ-MAINT-UPDATE - CLI support for updating annotation references
  * @req REQ-MAINT-BATCH - CLI support for batch maintenance operations
- * @req REQ-MAINT-SAFE - Provide clear exit codes and avoid unsafe defaults
+ * @req REQ-MAINT-MANUAL-TRIGGER - Maintenance tools run only when manually executed
  */
 export declare function runMaintenanceCli(rawArgv: string[]): number;

package/lib/maintenance/cli.js

@@ -7,18 +7,16 @@ const flags_1 = require("./flags");
 /**
  * Maintenance CLI entry point.
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-DETECT - CLI support for detection of stale annotations
- * @req REQ-MAINT-VERIFY - CLI support for verification of annotations
- * @req REQ-MAINT-REPORT - CLI support for human-readable reports
+ * @req REQ-MAINT-CLI - CLI support for maintenance commands
  * @req REQ-MAINT-UPDATE - CLI support for updating annotation references
  * @req REQ-MAINT-BATCH - CLI support for batch maintenance operations
- * @req REQ-MAINT-SAFE - Provide clear exit codes and avoid unsafe defaults
+ * @req REQ-MAINT-MANUAL-TRIGGER - Maintenance tools run only when manually executed
  */
 function runMaintenanceCli(rawArgv) {
     const initialNormalized = (0, flags_1.normalizeCliArgs)(rawArgv);
     const { subcommand: command } = initialNormalized;
     if (!command || command === "-h" || command === "--help") {
-        // @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-MANUAL-TRIGGER
         printHelp();
         return commands_1.EXIT_OK;
     }
@@ -26,35 +24,35 @@ function runMaintenanceCli(rawArgv) {
     // receive the subcommand name and its raw argument vector unchanged.
     const normalized = initialNormalized;
     try {
-        // @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-CLI
         switch (command) {
             case "detect":
-                // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
+                // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI
                 return (0, commands_1.handleDetect)(normalized);
             case "verify":
-                // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-VERIFY
+                // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI
                 return (0, commands_1.handleVerify)(normalized);
             case "report":
-                // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-REPORT
+                // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI
                 return (0, commands_1.handleReport)(normalized);
             case "update": {
                 // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE
                 const result = (0, commands_1.handleUpdate)(normalized);
                 if (result === commands_1.EXIT_USAGE) {
-                    // @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-MANUAL-TRIGGER
                     printHelp();
                 }
                 return result;
             }
             default:
-                // @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-MANUAL-TRIGGER
                 console.error(`Unknown command: ${command}`);
                 printHelp();
                 return commands_1.EXIT_USAGE;
         }
     }
     catch (error) {
-        // @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-MANUAL-TRIGGER
         const message = error instanceof Error
             ? error.message
             : "Unknown error in maintenance CLI";
@@ -65,10 +63,10 @@ function runMaintenanceCli(rawArgv) {
 /**
  * Print CLI usage help for the maintenance tools.
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-SAFE - Provide discoverable CLI usage information
+ * @req REQ-MAINT-MANUAL-TRIGGER - Provide discoverable CLI usage information
  */
 function printHelp() {
-    // @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-MANUAL-TRIGGER
     console.log(`traceability-maint - Traceability annotation maintenance tools
 
 Usage:

package/lib/maintenance/commands.d.ts

@@ -5,35 +5,35 @@ export declare const EXIT_USAGE = 2;
 /**
  * Handle the `detect` subcommand for stale story annotations.
  * @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-CLI - CLI surface for detection of stale annotations
+ * @req REQ-MAINT-CLI - 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
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI REQ-MAINT-CLI
  */
 export declare function handleDetect(normalized: NormalizedCliArgs): number;
 /**
  * Handle the `verify` subcommand to validate traceability annotations.
  * @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-CLI - CLI surface for verification of annotations
+ * @req REQ-MAINT-CLI - 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
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI REQ-MAINT-CLI
  */
 export declare function handleVerify(normalized: NormalizedCliArgs): number;
 /**
  * Handle the `report` subcommand to generate a maintenance report.
  * @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-CLI - CLI surface for human-readable maintenance reports
+ * @req REQ-MAINT-CLI - 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
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI REQ-MAINT-CLI
  */
 export declare function handleReport(normalized: NormalizedCliArgs): number;
 /**
  * Handle the `update` subcommand to rewrite story annotation references.
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UPDATE - CLI surface for updating annotation references
- * @req REQ-MAINT-SAFE - Provide dry-run mode and explicit parameter checks
- * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE REQ-MAINT-SAFE
+ * @req REQ-MAINT-CLI - Provide dry-run mode and explicit parameter checks
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE REQ-MAINT-CLI
  */
 export declare function handleUpdate(normalized: NormalizedCliArgs): number;

package/lib/maintenance/commands.js

@@ -9,11 +9,11 @@ exports.handleUpdate = handleUpdate;
  * Subcommand handlers for the traceability-maint CLI.
  *
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-DETECT - CLI support for detection of stale annotations.
- * @req REQ-MAINT-VERIFY - CLI support for verification of annotations
- * @req REQ-MAINT-REPORT - CLI support for human-readable reports
+ * @req REQ-MAINT-CLI - CLI support for detection of stale annotations.
+ * @req REQ-MAINT-CLI - CLI support for verification of annotations
+ * @req REQ-MAINT-CLI - CLI support for human-readable reports
  * @req REQ-MAINT-UPDATE - CLI support for updating annotation references
- * @req REQ-MAINT-SAFE - Provide clear exit codes and avoid unsafe defaults
+ * @req REQ-MAINT-CLI - Provide clear exit codes and avoid unsafe defaults
  */
 const detect_1 = require("./detect");
 const batch_1 = require("./batch");
@@ -26,10 +26,10 @@ exports.EXIT_USAGE = 2;
 /**
  * Handle the `detect` subcommand for stale story annotations.
  * @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-CLI - CLI surface for detection of stale annotations
+ * @req REQ-MAINT-CLI - 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
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI REQ-MAINT-CLI
  */
 function handleDetect(normalized) {
     const flags = (0, flags_1.parseFlags)(normalized);
@@ -57,10 +57,10 @@ Run 'traceability-maint report' for a structured summary.`);
 /**
  * Handle the `verify` subcommand to validate traceability annotations.
  * @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-CLI - CLI surface for verification of annotations
+ * @req REQ-MAINT-CLI - 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
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI REQ-MAINT-CLI
  */
 function handleVerify(normalized) {
     const flags = (0, flags_1.parseFlags)(normalized);
@@ -79,10 +79,10 @@ function handleVerify(normalized) {
 /**
  * Handle the `report` subcommand to generate a maintenance report.
  * @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-CLI - CLI surface for human-readable maintenance reports
+ * @req REQ-MAINT-CLI - 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
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI REQ-MAINT-CLI
  */
 function handleReport(normalized) {
     const flags = (0, flags_1.parseFlags)(normalized);
@@ -109,7 +109,7 @@ function handleReport(normalized) {
 /**
  * Handle dry-run mode for update command
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-SAFE
+ * @req REQ-MAINT-CLI
  */
 function handleUpdateDryRun(root, from, to, flags) {
     const options = flags.ignorePatterns
@@ -137,8 +137,8 @@ function handleUpdateDryRun(root, from, to, flags) {
  * Handle the `update` subcommand to rewrite story annotation references.
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UPDATE - CLI surface for updating annotation references
- * @req REQ-MAINT-SAFE - Provide dry-run mode and explicit parameter checks
- * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE REQ-MAINT-SAFE
+ * @req REQ-MAINT-CLI - Provide dry-run mode and explicit parameter checks
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE REQ-MAINT-CLI
  */
 function handleUpdate(normalized) {
     const flags = (0, flags_1.parseFlags)(normalized);

package/lib/maintenance/detect.d.ts

@@ -2,7 +2,7 @@ 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-CLI - 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

package/lib/maintenance/detect.js

@@ -41,7 +41,7 @@ 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-CLI - 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
@@ -50,24 +50,24 @@ const storyReferenceUtils_1 = require("../utils/storyReferenceUtils");
 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()
+    // @req REQ-MAINT-CLI - Treat codebasePath as a workspace root resolved from process.cwd()
     const workspaceRoot = path.resolve(cwd, codebasePath);
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-    // @req REQ-MAINT-DETECT - Return empty result if workspaceRoot does not exist or is not a directory
+    // @req REQ-MAINT-CLI - Return empty result if workspaceRoot does not exist or is not a directory
     if (!fs.existsSync(workspaceRoot) ||
         !fs.statSync(workspaceRoot).isDirectory()) {
-        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
-        // @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-DETECT
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI
         return [];
     }
     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
+    // @req REQ-MAINT-CLI - Iterate over all files in the isolated workspace root
     // @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
+    // @req REQ-MAINT-CLI - Loop over each workspace file to inspect its @story annotations
     for (const file of files) {
         processFileForStaleAnnotations(file, workspaceRoot, cwd, stale);
     }
@@ -75,88 +75,88 @@ function detectStaleAnnotations(codebasePath, options) {
 }
 /**
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-DETECT - Process individual files to detect stale @story annotations
+ * @req REQ-MAINT-CLI - Process individual files to detect stale @story annotations
  */
 function processFileForStaleAnnotations(file, workspaceRoot, cwd, stale) {
     let content;
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-    // @req REQ-MAINT-DETECT - Handle file read errors gracefully
+    // @req REQ-MAINT-CLI - Handle file read errors gracefully
     try {
-        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI
         content = fs.readFileSync(file, "utf8");
     }
     catch {
-        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
-        // @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-CLI
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI
         return;
     }
     const regex = /@story\s+([^\s]+)/g;
     let match;
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-    // @req REQ-MAINT-DETECT - Iterate over regex matches for @story annotations
+    // @req REQ-MAINT-CLI - Iterate over regex matches for @story annotations
     while ((match = regex.exec(content)) !== null) {
         handleStoryMatch(match[1], workspaceRoot, cwd, stale);
     }
 }
 /**
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-DETECT REQ-SECURITY-VALIDATION - Handle individual @story matches within a file
+ * @req REQ-MAINT-CLI REQ-SECURITY-VALIDATION - Handle individual @story matches within a file
  */
 function handleStoryMatch(storyPath, workspaceRoot, cwd, stale) {
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-    // @req REQ-MAINT-DETECT REQ-SECURITY-VALIDATION - Skip traversal/absolute-unsafe or invalid-extension story paths before any filesystem or boundary checks
+    // @req REQ-MAINT-CLI REQ-SECURITY-VALIDATION - Skip traversal/absolute-unsafe or invalid-extension story paths before any filesystem or boundary checks
     if ((0, storyReferenceUtils_1.isUnsafeStoryPath)(storyPath)) {
-        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI
         return;
     }
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-    // @req REQ-MAINT-DETECT - Compute project and codebase candidates relative to cwd and workspaceRoot
+    // @req REQ-MAINT-CLI - Compute project and codebase candidates relative to cwd and workspaceRoot
     const storyProjectCandidate = path.resolve(cwd, storyPath);
     const storyCodebaseCandidate = path.resolve(workspaceRoot, storyPath);
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-    // @req REQ-MAINT-DETECT - Enforce workspaceRoot as the project boundary for resolved story paths
+    // @req REQ-MAINT-CLI - Enforce workspaceRoot as the project boundary for resolved story paths
     const inProjectCandidates = getInProjectCandidates(storyProjectCandidate, storyCodebaseCandidate, workspaceRoot);
     // If both candidates are out-of-project, do not mark as stale and skip FS checks
     if (inProjectCandidates.length === 0) {
-        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI
         return;
     }
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-    // @req REQ-MAINT-DETECT - Only check existence for in-project candidates
+    // @req REQ-MAINT-CLI - Only check existence for in-project candidates
     const anyExists = anyInProjectCandidateExists(inProjectCandidates);
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-    // @req REQ-MAINT-DETECT - Mark story as stale if any in-project candidate exists conceptually but none exist on disk
+    // @req REQ-MAINT-CLI - Mark story as stale if any in-project candidate exists conceptually but none exist on disk
     if (!anyExists) {
-        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI
         stale.add(storyPath);
     }
 }
 /**
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-DETECT - Enforce project boundary and return in-project candidates
+ * @req REQ-MAINT-CLI - Enforce project boundary and return in-project candidates
  */
 function getInProjectCandidates(storyProjectCandidate, storyCodebaseCandidate, workspaceRoot) {
     let projectBoundary;
     let codebaseBoundary;
     try {
-        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI
         projectBoundary = (0, storyReferenceUtils_1.enforceProjectBoundary)(storyProjectCandidate, workspaceRoot);
     }
     catch {
-        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
-        // @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-CLI
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI
         projectBoundary = {
             isWithinProject: false,
             candidate: storyProjectCandidate,
         };
     }
     try {
-        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI
         codebaseBoundary = (0, storyReferenceUtils_1.enforceProjectBoundary)(storyCodebaseCandidate, workspaceRoot);
     }
     catch {
-        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
-        // @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-CLI
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI
         codebaseBoundary = {
             isWithinProject: false,
             candidate: storyCodebaseCandidate,
@@ -164,28 +164,28 @@ function getInProjectCandidates(storyProjectCandidate, storyCodebaseCandidate, w
     }
     const inProjectCandidates = [];
     if (projectBoundary.isWithinProject) {
-        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI
         inProjectCandidates.push(projectBoundary.candidate);
     }
     if (codebaseBoundary.isWithinProject) {
-        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
+        // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI
         inProjectCandidates.push(codebaseBoundary.candidate);
     }
     return inProjectCandidates;
 }
 /**
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-DETECT - Check on-disk existence of in-project candidates
+ * @req REQ-MAINT-CLI - Check on-disk existence of in-project candidates
  */
 function anyInProjectCandidateExists(inProjectCandidates) {
     return inProjectCandidates.some(
     /**
-     * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-SAFE
+     * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-CLI REQ-MAINT-CLI
      */
     (p) => {
         const exists = fs.existsSync(p);
         if (!exists) {
-            // @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-CLI
         }
         return exists;
     });

package/lib/maintenance/flags.d.ts

@@ -4,7 +4,7 @@
  * Separates Node/V8 internals from the actual subcommand and its arguments.
  *
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ * @req REQ-MAINT-CLI - Provide predictable, minimal argument parsing
  */
 export interface ParsedCliInput {
     /**
@@ -39,7 +39,7 @@ export interface ParsedCliInput {
  * @returns ParsedCliInput with node, script, subcommand, and remaining args.
  *
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ * @req REQ-MAINT-CLI - Provide predictable, minimal argument parsing
  */
 export declare function parseCliInput(argv: string[]): ParsedCliInput;
 /**
@@ -49,7 +49,7 @@ export declare function parseCliInput(argv: string[]): ParsedCliInput;
  * subcommand name and its raw arguments for further flag parsing.
  *
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ * @req REQ-MAINT-CLI - Provide predictable, minimal argument parsing
  */
 export interface NormalizedCliArgs {
     /**
@@ -73,7 +73,7 @@ export interface NormalizedCliArgs {
  * @returns NormalizedCliArgs with subcommand and remaining args.
  *
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ * @req REQ-MAINT-CLI - Provide predictable, minimal argument parsing
  */
 export declare function normalizeCliArgs(rawArgv: string[]): NormalizedCliArgs;
 export interface ParsedFlags {
@@ -95,6 +95,6 @@ export interface ParsedFlags {
  * @returns ParsedFlags with defaults applied and any recognized flags set.
  *
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ * @req REQ-MAINT-CLI - Provide predictable, minimal argument parsing
  */
 export declare function parseFlags(normalized: NormalizedCliArgs): ParsedFlags;