eslint-plugin-traceability 1.6.5 → 1.7.1

package/README.md

@@ -8,7 +8,7 @@ Created autonomously by [voder.ai](https://voder.ai).
 
 ## Installation
 
-Prerequisites: Node.js >=14 and ESLint v9+.
+Prerequisites: Node.js >=18.18.0 and ESLint v9+.
 
 1. Using npm  
    npm install --save-dev eslint-plugin-traceability
@@ -54,6 +54,7 @@ module.exports = [
 - `traceability/valid-annotation-format` Enforces correct format of traceability annotations. ([Documentation](docs/rules/valid-annotation-format.md))
 - `traceability/valid-story-reference` Validates that `@story` references point to existing story files. ([Documentation](docs/rules/valid-story-reference.md))
 - `traceability/valid-req-reference` Validates that `@req` references point to existing requirement IDs. ([Documentation](docs/rules/valid-req-reference.md))
+- `traceability/prefer-implements-annotation` Recommends migration from legacy `@story`/`@req` annotations to `@implements` (disabled by default). ([Documentation](docs/rules/prefer-implements-annotation.md))
 
 Configuration options: For detailed per-rule options (such as scopes, branch types, and story directory settings), see the individual rule docs in `docs/rules/` and the consolidated [API Reference](user-docs/api-reference.md).
 
@@ -99,6 +100,43 @@ Detailed API specification and configuration options can be found in the [API Re
 
 Practical usage examples and sample configurations are available in the [Examples](user-docs/examples.md) document.
 
+## 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.
+
+### Commands
+
+- `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).
+
+### Usage
+
+All commands are run from your project root:
+
+```bash
+# Show help and all options
+npx traceability-maint --help
+
+# Detect stale story references
+npx traceability-maint detect --root .
+
+# Verify that annotations are valid
+npx traceability-maint verify --root .
+
+# Generate a JSON report for CI pipelines
+npx traceability-maint report --root . --format json
+
+# Update references when a story file is renamed
+npx traceability-maint update \
+  --root . \
+  --from "docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md" \
+  --to "docs/stories/003.0-DEV-FN-ANNOTATIONS.story.md"
+```
+
+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
 
 You can validate the plugin by running ESLint CLI with the plugin on a sample file:

package/lib/src/index.d.ts

@@ -5,11 +5,16 @@
  * @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";
 /**
  * @story docs/stories/002.0-DYNAMIC-RULE-LOADING.story.md
  * @req REQ-RULE-LIST - Enumerate supported rule file names for plugin discovery
  */
-declare const RULE_NAMES: readonly ["require-story-annotation", "require-req-annotation", "require-branch-annotation", "valid-annotation-format", "valid-story-reference", "valid-req-reference"];
+declare const RULE_NAMES: readonly ["require-story-annotation", "require-req-annotation", "require-branch-annotation", "valid-annotation-format", "valid-story-reference", "valid-req-reference", "prefer-implements-annotation"];
 type RuleName = (typeof RULE_NAMES)[number];
 declare const rules: Record<RuleName, Rule.RuleModule>;
 /**
@@ -24,12 +29,7 @@ declare const configs: {
             traceability: {};
         };
         rules: {
-            "traceability/require-story-annotation": string;
-            "traceability/require-req-annotation": string;
-            "traceability/require-branch-annotation": string;
-            "traceability/valid-annotation-format": string;
-            "traceability/valid-story-reference": string;
-            "traceability/valid-req-reference": string;
+            [x: string]: "error" | "warn";
         };
     }[];
     strict: {
@@ -37,30 +37,31 @@ declare const configs: {
             traceability: {};
         };
         rules: {
-            "traceability/require-story-annotation": string;
-            "traceability/require-req-annotation": string;
-            "traceability/require-branch-annotation": string;
-            "traceability/valid-annotation-format": string;
-            "traceability/valid-story-reference": string;
-            "traceability/valid-req-reference": string;
+            [x: string]: "error" | "warn";
         };
     }[];
 };
-export { rules, 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;
+    batchUpdateAnnotations: typeof batchUpdateAnnotations;
+    verifyAnnotations: typeof verifyAnnotations;
+    generateMaintenanceReport: typeof generateMaintenanceReport;
+};
+export { rules, configs, maintenance };
 declare const _default: {
-    rules: Record<"require-story-annotation" | "require-req-annotation" | "require-branch-annotation" | "valid-annotation-format" | "valid-story-reference" | "valid-req-reference", Rule.RuleModule>;
+    rules: Record<"require-story-annotation" | "require-req-annotation" | "require-branch-annotation" | "valid-annotation-format" | "valid-story-reference" | "valid-req-reference" | "prefer-implements-annotation", Rule.RuleModule>;
     configs: {
         recommended: {
             plugins: {
                 traceability: {};
             };
             rules: {
-                "traceability/require-story-annotation": string;
-                "traceability/require-req-annotation": string;
-                "traceability/require-branch-annotation": string;
-                "traceability/valid-annotation-format": string;
-                "traceability/valid-story-reference": string;
-                "traceability/valid-req-reference": string;
+                [x: string]: "error" | "warn";
             };
         }[];
         strict: {
@@ -68,14 +69,16 @@ declare const _default: {
                 traceability: {};
             };
             rules: {
-                "traceability/require-story-annotation": string;
-                "traceability/require-req-annotation": string;
-                "traceability/require-branch-annotation": string;
-                "traceability/valid-annotation-format": string;
-                "traceability/valid-story-reference": string;
-                "traceability/valid-req-reference": string;
+                [x: string]: "error" | "warn";
             };
         }[];
     };
+    maintenance: {
+        detectStaleAnnotations: typeof detectStaleAnnotations;
+        updateAnnotationReferences: typeof updateAnnotationReferences;
+        batchUpdateAnnotations: typeof batchUpdateAnnotations;
+        verifyAnnotations: typeof verifyAnnotations;
+        generateMaintenanceReport: typeof generateMaintenanceReport;
+    };
 };
 export default _default;

package/lib/src/index.js

@@ -1,6 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.configs = exports.rules = void 0;
+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-DYNAMIC-RULE-LOADING.story.md
  * @req REQ-RULE-LIST - Enumerate supported rule file names for plugin discovery
@@ -12,6 +17,7 @@ const RULE_NAMES = [
     "valid-annotation-format",
     "valid-story-reference",
     "valid-req-reference",
+    "prefer-implements-annotation",
 ];
 const rules = {};
 exports.rules = rules;
@@ -73,37 +79,51 @@ RULE_NAMES.forEach(
  * The recommended and strict configs treat missing annotations and missing references as errors,
  * while formatting issues are reported as warnings, matching the story's severity conventions.
  */
-const configs = {
-    recommended: [
-        {
-            plugins: {
-                traceability: {},
-            },
-            rules: {
-                "traceability/require-story-annotation": "error",
-                "traceability/require-req-annotation": "error",
-                "traceability/require-branch-annotation": "error",
-                "traceability/valid-annotation-format": "warn",
-                "traceability/valid-story-reference": "error",
-                "traceability/valid-req-reference": "error",
-            },
+const TRACEABILITY_RULE_SEVERITIES = {
+    "traceability/require-story-annotation": "error",
+    "traceability/require-req-annotation": "error",
+    "traceability/require-branch-annotation": "error",
+    "traceability/valid-annotation-format": "warn",
+    "traceability/valid-story-reference": "error",
+    "traceability/valid-req-reference": "error",
+    "traceability/prefer-implements-annotation": "warn",
+};
+/**
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @req REQ-PLUGIN-STRUCTURE - Provide foundational plugin export and registration
+ * @req REQ-ERROR-SEVERITY - Map rule types to appropriate ESLint severity levels (errors vs warnings)
+ */
+function createTraceabilityFlatConfig() {
+    return {
+        plugins: {
+            traceability: {},
         },
-    ],
-    strict: [
-        {
-            plugins: {
-                traceability: {},
-            },
-            rules: {
-                "traceability/require-story-annotation": "error",
-                "traceability/require-req-annotation": "error",
-                "traceability/require-branch-annotation": "error",
-                "traceability/valid-annotation-format": "warn",
-                "traceability/valid-story-reference": "error",
-                "traceability/valid-req-reference": "error",
-            },
+        rules: {
+            ...TRACEABILITY_RULE_SEVERITIES,
         },
-    ],
+    };
+}
+/**
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @req REQ-ERROR-SEVERITY - Map rule types to appropriate ESLint severity levels (errors vs warnings)
+ * The recommended and strict configs treat missing annotations and missing references as errors,
+ * while formatting issues are reported as warnings, matching the story's severity conventions.
+ */
+const configs = {
+    recommended: [createTraceabilityFlatConfig()],
+    strict: [createTraceabilityFlatConfig()],
 };
 exports.configs = configs;
-exports.default = { rules, 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,
+    batchUpdateAnnotations: maintenance_1.batchUpdateAnnotations,
+    verifyAnnotations: maintenance_1.verifyAnnotations,
+    generateMaintenanceReport: maintenance_1.generateMaintenanceReport,
+};
+exports.maintenance = maintenance;
+exports.default = { rules, configs, maintenance };

package/lib/src/maintenance/cli.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * 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-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
+ */
+export declare function runMaintenanceCli(rawArgv: string[]): number;

package/lib/src/maintenance/cli.js

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMaintenanceCli = runMaintenanceCli;
+const path_1 = __importDefault(require("path"));
+const detect_1 = require("./detect");
+const batch_1 = require("./batch");
+const update_1 = require("./update");
+const report_1 = require("./report");
+const EXIT_OK = 0;
+const EXIT_STALE = 1;
+const EXIT_USAGE = 2;
+/**
+ * Extract the subcommand and its arguments from a raw argv array.
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Centralize parsing of CLI command and arguments
+ */
+function parseCliInput(rawArgv) {
+    const [, , command, ...rest] = rawArgv;
+    return { command, args: rest };
+}
+/**
+ * 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-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
+ */
+function runMaintenanceCli(rawArgv) {
+    const { command, args } = parseCliInput(rawArgv);
+    if (!command || command === "-h" || command === "--help") {
+        printHelp();
+        return EXIT_OK;
+    }
+    try {
+        switch (command) {
+            case "detect":
+                return handleDetect(args);
+            case "verify":
+                return handleVerify(args);
+            case "report":
+                return handleReport(args);
+            case "update":
+                return handleUpdate(args);
+            default:
+                console.error(`Unknown command: ${command}`);
+                printHelp();
+                return EXIT_USAGE;
+        }
+    }
+    catch (error) {
+        // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+        // @req REQ-MAINT-SAFE - Catch unexpected errors and emit concise diagnostics
+        const message = error instanceof Error
+            ? error.message
+            : "Unknown error in maintenance CLI";
+        console.error(`traceability-maint failed: ${message}`);
+        return EXIT_USAGE;
+    }
+}
+/**
+ * Initialize default flags for the maintenance CLI.
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ */
+function createDefaultFlags() {
+    return {
+        root: process.cwd(),
+        json: false,
+    };
+}
+/**
+ * Handle a single CLI argument and update the flags accordingly.
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ */
+function applyFlag(flags, args, index) {
+    const arg = args[index];
+    if (arg === "--root" && typeof args[index + 1] === "string") {
+        flags.root = path_1.default.resolve(args[index + 1]);
+        return index + 1;
+    }
+    if (arg === "--json") {
+        flags.json = true;
+        return index;
+    }
+    if (arg === "--format" && typeof args[index + 1] === "string") {
+        const value = args[index + 1];
+        if (value === "text" || value === "json") {
+            flags.format = value;
+        }
+        else {
+            throw new Error(`Invalid format: ${value}. Expected 'text' or 'json'.`);
+        }
+        return index + 1;
+    }
+    if (arg === "--from" && typeof args[index + 1] === "string") {
+        flags.from = args[index + 1];
+        return index + 1;
+    }
+    if (arg === "--to" && typeof args[index + 1] === "string") {
+        flags.to = args[index + 1];
+        return index + 1;
+    }
+    if (arg === "--dry-run") {
+        flags.dryRun = true;
+        return index;
+    }
+    return index;
+}
+/**
+ * Basic flag parser for maintenance CLI subcommands.
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ */
+function parseFlags(args) {
+    const flags = createDefaultFlags();
+    for (let i = 0; i < args.length; i += 1) {
+        i = applyFlag(flags, args, i);
+    }
+    return flags;
+}
+/**
+ * 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
+ */
+function handleDetect(args) {
+    const flags = parseFlags(args);
+    const root = flags.root;
+    const stale = (0, detect_1.detectStaleAnnotations)(root);
+    if (flags.json) {
+        // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+        // @req REQ-MAINT-REPORT - JSON-friendly output for tooling integration
+        console.log(JSON.stringify({ root, stale }));
+    }
+    else {
+        if (stale.length === 0) {
+            console.log("No stale @story annotations found.");
+        }
+        else {
+            stale.forEach((story) => {
+                console.log(story);
+            });
+            console.log(`Found ${stale.length} stale @story annotation${stale.length === 1 ? "" : "s"}.
+Run 'traceability-maint report' for a structured summary.`);
+        }
+    }
+    return stale.length === 0 ? EXIT_OK : EXIT_STALE;
+}
+/**
+ * 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
+ */
+function handleVerify(args) {
+    const flags = parseFlags(args);
+    const root = flags.root;
+    const valid = (0, batch_1.verifyAnnotations)(root);
+    if (valid) {
+        console.log(`All traceability annotations under ${root} are valid.`);
+        return EXIT_OK;
+    }
+    console.log(`Stale or invalid traceability annotations detected under ${root}.\nRun 'traceability-maint detect' or 'traceability-maint report' for details.`);
+    return EXIT_STALE;
+}
+/**
+ * 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
+ */
+function handleReport(args) {
+    const flags = parseFlags(args);
+    const root = flags.root;
+    const format = flags.format ?? "text";
+    const report = (0, report_1.generateMaintenanceReport)(root);
+    if (format === "json") {
+        console.log(JSON.stringify({ root, report }));
+    }
+    else {
+        if (!report) {
+            console.log("No stale @story annotations found. Nothing to report.");
+        }
+        else {
+            console.log(`# Traceability Maintenance Report for ${root}`);
+            console.log("");
+            console.log("Stale story references:");
+            console.log(report);
+        }
+    }
+    return EXIT_OK;
+}
+/**
+ * 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
+ */
+function handleUpdate(args) {
+    const flags = parseFlags(args);
+    const root = flags.root;
+    if (!flags.from || !flags.to) {
+        console.error("'update' requires --from <oldPath> and --to <newPath>.");
+        printHelp();
+        return EXIT_USAGE;
+    }
+    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 = {
+            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 EXIT_OK;
+    }
+    const count = (0, update_1.updateAnnotationReferences)(root, from, to);
+    if (flags.json) {
+        console.log(JSON.stringify({ root, from, to, updated: count }));
+    }
+    else {
+        console.log(`Updated ${count} @story annotation${count === 1 ? "" : "s"} from '${from}' to '${to}' under ${root}.`);
+    }
+    return EXIT_OK;
+}
+/**
+ * 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
+ */
+function printHelp() {
+    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+    // @req REQ-MAINT-SAFE - Provide discoverable CLI usage information
+    console.log(`traceability-maint - Traceability annotation maintenance tools
+
+Usage:
+  traceability-maint <command> [options]
+
+Commands:
+  detect   Detect stale @story annotations
+  verify   Verify that traceability annotations are valid
+  report   Generate a maintenance report
+  update   Update @story annotation references
+
+Options:
+  --root <dir>        Workspace root to scan (defaults to current directory)
+  --json              Output JSON where supported
+  --format <text|json>  Output format for 'report' (default: text)
+  --from <oldPath>    Old story path for 'update'
+  --to <newPath>      New story path for 'update'
+  --dry-run           Plan changes for 'update' without modifying files
+  -h, --help          Show this help message
+`);
+}
+if (require.main === module) {
+    process.exit(runMaintenanceCli(process.argv));
+}

package/lib/src/maintenance/detect.js

@@ -101,6 +101,25 @@ function handleStoryMatch(storyPath, workspaceRoot, cwd, stale) {
     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
+    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) {
+        return;
+    }
+    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+    // @req REQ-MAINT-DETECT - 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
+    if (!anyExists) {
+        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
+ */
+function getInProjectCandidates(storyProjectCandidate, storyCodebaseCandidate, workspaceRoot) {
     let projectBoundary;
     let codebaseBoundary;
     try {
@@ -128,16 +147,12 @@ function handleStoryMatch(storyPath, workspaceRoot, cwd, stale) {
     if (codebaseBoundary.isWithinProject) {
         inProjectCandidates.push(codebaseBoundary.candidate);
     }
-    // If both candidates are out-of-project, do not mark as stale and skip FS checks
-    if (inProjectCandidates.length === 0) {
-        return;
-    }
-    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-    // @req REQ-MAINT-DETECT - Only check existence for in-project candidates
-    const anyExists = inProjectCandidates.some((p) => fs.existsSync(p));
-    // @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
-    if (!anyExists) {
-        stale.add(storyPath);
-    }
+    return inProjectCandidates;
+}
+/**
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-DETECT - Check on-disk existence of in-project candidates
+ */
+function anyInProjectCandidateExists(inProjectCandidates) {
+    return inProjectCandidates.some((p) => fs.existsSync(p));
 }