eslint-plugin-traceability 1.8.1 → 1.8.2

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [1.8.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.8.0...v1.8.1) (2025-12-04)
+## [1.8.2](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.8.1...v1.8.2) (2025-12-04)
 
 
 ### Bug Fixes
 
-* disable prefer-implements-annotation in default presets ([89c62e9](https://github.com/voder-ai/eslint-plugin-traceability/commit/89c62e907be95030f89e6a3ab6df24a4ba32ab62))
+* rename multi-story annotation from [@implements](https://github.com/implements) to [@supports](https://github.com/supports) ([8c5d089](https://github.com/voder-ai/eslint-plugin-traceability/commit/8c5d08997efb4e5ab8f565db462633b15232ded0))
 
 # Changelog
 
@@ -75,8 +75,8 @@ The following entries were maintained manually before the adoption of semantic-r
   - `valid-annotation-format`
   - `valid-story-reference`
   - `valid-req-reference`
-- Documentation for all rules under `docs/rules`.
-- Configuration presets in `docs/config-presets.md`.
+- Developer documentation for all rules in this repository.
+- Developer documentation for configuration presets in this repository.
 - Example usage in `README.md`.
 - Pre-commit and pre-push hooks with formatting, linting, and tests.
 - Comprehensive tests covering core validation rules.

package/README.md

@@ -54,7 +54,7 @@ export default [
 - `traceability/valid-annotation-format` Enforces correct format of traceability annotations. (See the rule documentation in the plugin's user guide.)
 - `traceability/valid-story-reference` Validates that `@story` references point to existing story files. (See the rule documentation in the plugin's user guide.)
 - `traceability/valid-req-reference` Validates that `@req` references point to existing requirement IDs. (See the rule documentation in the plugin's user guide.)
-- `traceability/prefer-implements-annotation` Recommends migration from legacy `@story`/`@req` annotations to `@implements` (opt-in; disabled by default in the presets and must be explicitly enabled). (See the rule documentation in the plugin's user guide.)
+- `traceability/prefer-implements-annotation` Recommends migration from legacy `@story`/`@req` annotations to `@supports` (opt-in; disabled by default in the presets and must be explicitly enabled). (See the rule documentation in the plugin's user guide.)
 
 Configuration options: For detailed per-rule options (such as scopes, branch types, and story directory settings), see the individual rule docs in the plugin's user guide and the consolidated [API Reference](user-docs/api-reference.md).
 
@@ -136,8 +136,8 @@ 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"
+  --from "stories/feature-authentication.story.md" \
+  --to "stories/feature-auth-v2.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.
@@ -195,7 +195,7 @@ These tests verify end-to-end behavior of the plugin via the ESLint CLI.
 
 ## Security and Dependency Health
 
-For the canonical, user-facing security policy (including how to report vulnerabilities), see [SECURITY.md](SECURITY.md). The additional files under `docs/` referenced below provide deeper background and implementation details for interested readers.
+For the canonical, user-facing security policy (including how to report vulnerabilities), see [SECURITY.md](SECURITY.md). Internal implementation details and deeper discussion live in the project’s internal documentation and decision records, which are intended for maintainers rather than end users.
 
 ### What end users can expect from production dependencies
 

package/SECURITY.md

@@ -4,6 +4,8 @@ This document describes how security is handled for `eslint-plugin-traceability`
 
 > This file is **user-facing** documentation. Internal implementation details and deeper discussion live in the project’s internal documentation and decision records.
 
+For a consolidated implementation overview of security tooling and checks (maintainer and automated-assessor focused), maintainers can refer to the project's internal security overview documentation; this level of detail is not required for normal end users of the plugin.
+
 ## Reporting a Vulnerability
 
 If you believe you have found a security vulnerability in this project:
@@ -41,7 +43,9 @@ In other words:
 - The published npm package is intended to ship **without known high‑severity vulnerabilities in its production dependencies** at the moment it is released.
 - Dev-only tooling and CI infrastructure are kept separate from what you install via `npm install eslint-plugin-traceability`.
 
-For more detail on how these checks are wired into CI, see the internal dependency health and security documentation for this project.
+For more detail on how these checks are wired into CI, maintainers can refer to the project’s internal dependency health and security documentation; this level of detail is not required for normal end users of the plugin.
+
+Maintainer-focused CI/CD security summary: release workflows enforce several security checks end-to-end. For production dependencies, `npm audit --omit=dev --audit-level=high` is **release-blocking** and must report no high-severity issues before publishing proceeds. For broader dependency health, `npm run safety:deps` (dry-aged-deps) and `npm run audit:dev-high` (dev-only `npm audit` with stricter thresholds) are **advisory**: they generate machine-readable reports to guide upgrades and risk review but do not, by themselves, block a release. Secret scanning is performed with `npm run security:secrets` (secretlint); this is treated as **release-blocking** in CI/CD so that accidental credential or secret leaks are caught before artifacts are published.
 
 ## Dependency Maturity and `dry-aged-deps`
 
@@ -59,71 +63,70 @@ Current high-level policy:
 
 When `dry-aged-deps` reports that there are **no safe upgrades available** under these thresholds, we may temporarily accept residual risk in dev-only tooling while keeping production dependencies clean and fully audited.
 
-For maintainers, the full process is described in the project’s internal dependency health and security guidelines.
+For maintainers, the full process is described in the project’s internal dependency health and security guidelines; end users typically do not need to consult those documents.
 
 ## Dev-Only Release Tooling Risk (semantic-release / npm / glob / brace-expansion)
 
-There is a known, documented risk in the **dev-only release toolchain** used by this project. It does **not** affect the runtime behavior of the published ESLint plugin or CLI, but it is relevant to how releases are built in CI.
+This section documents a **historical** dev-only risk in an older semantic-release/npm toolchain that has since been fully resolved by upgrading the release toolchain to a vulnerability-free stack.
+
+### What was affected?
 
-### What is affected?
+During the incident period, the **older** dev dependency stack had the following characteristics:
 
-- The dev dependency `@semantic-release/npm@10.0.6` bundles `npm@9.5.0`, which in turn includes vulnerable versions of `glob` and `brace-expansion`.
-- The relevant advisories are:
+- The dev dependency `@semantic-release/npm@10.0.6` bundled `npm@9.5.0`, which in turn included vulnerable versions of `glob` and `brace-expansion`.
+- The relevant advisories were:
   - `glob` CLI command injection: [GHSA-5j98-mcp5-4vw2](https://github.com/advisories/GHSA-5j98-mcp5-4vw2)
   - `brace-expansion` ReDoS: [GHSA-v6h2-p8h4-qcjw](https://github.com/advisories/GHSA-v6h2-p8h4-qcjw)
-- These vulnerable packages exist **only inside the npm binary bundled within `@semantic-release/npm`** and are used solely during automated publishing from CI.
+- These vulnerable packages existed **only inside the npm binary bundled within `@semantic-release/npm`** and were used solely during automated publishing from CI.
+
+The current release toolchain no longer relies on this vulnerable bundled npm stack, and these specific advisories are no longer present in our dev dependencies.
 
 ### What is _not_ affected?
 
-- The published `eslint-plugin-traceability` package has **no runtime dependencies** on this bundled npm or its `glob`/`brace-expansion` copies.
+Throughout the incident period, and continuing after the upgrade:
+
+- The published `eslint-plugin-traceability` package has **no runtime dependencies** on any bundled npm or its `glob`/`brace-expansion` copies.
 - End-user projects that install and run `eslint-plugin-traceability` or `traceability-maint` **do not execute** this bundled tooling.
-- `npm audit --omit=dev --audit-level=high` continues to report **0 high‑severity vulnerabilities** for the production dependency tree at release time.
+- `npm audit --omit=dev --audit-level=high` has continued to report **0 high‑severity vulnerabilities** for the production dependency tree at release time.
 
-### Why is this risk currently accepted?
+These guarantees remain in effect with the updated, vulnerability-free toolchain.
 
-Under our `dry-aged-deps` policy (7‑day minimum age, no known vulnerabilities):
+### Historical Risk Acceptance
 
-- There is currently **no recommended, dry‑aged‑safe upgrade path** for the semantic-release/npm toolchain that would fully eliminate these bundled vulnerabilities.
-- We therefore treat this as a **known error in dev-only tooling** rather than a production risk.
+While the older `@semantic-release/npm@10.0.6` stack was in use and no safe, `dry-aged-deps`–approved upgrade path existed, this dev-only risk was **explicitly accepted** as a known error under the `dry-aged-deps` policy. It is **no longer** an active known error following the toolchain upgrade.
 
-This acceptance is documented in detail in the project’s internal security incident records and architectural decision records.
+The full historical record and resolution details are documented in:
+
+- A detailed historical incident report in this repository’s internal security incident documentation (maintainer-facing only)
 
 ### Compensating Controls
 
-To keep this dev-only risk tightly contained, we apply several compensating controls:
+While the older toolchain was in place, we applied several compensating controls to tightly contain the dev-only risk. The same general isolation and audit practices continue to apply to the updated, vulnerability-free release toolchain:
 
 1. **Environment Isolation**
-   - The vulnerable tooling is used **only** in the GitHub Actions CI workflow (`.github/workflows/ci-cd.yml`).
-   - It runs in a single, controlled job that executes on pushes to the `main` branch, not for pull requests.
-   - The job runs on GitHub-hosted runners and does not have access to internal infrastructure.
+   - The vulnerable tooling was used **only** in the GitHub Actions CI workflow (`.github/workflows/ci-cd.yml`).
+   - It ran in a single, controlled job that executed on pushes to the `main` branch, not for pull requests.
+   - The job ran on GitHub-hosted runners and did not have access to internal infrastructure.
 
 2. **Least-Privilege Permissions for Release**
-   - Workflow-level permissions default to `contents: read`.
-   - Elevated permissions (`contents: write`, `issues: write`, `pull-requests: write`, `id-token: write`) are scoped to the release job/step that runs semantic-release and are not used for general CI tasks.
+   - Workflow-level permissions defaulted to `contents: read`.
+   - Elevated permissions (`contents: write`, `issues: write`, `pull-requests: write`, `id-token: write`) were scoped to the release job/step that ran semantic-release and were not used for general CI tasks.
 
 3. **Strict Input Handling**
-   - The CI configuration and project scripts **never invoke the `glob` CLI** with the dangerous `-c/--cmd` flags.
-   - The semantic-release/npm toolchain does **not** receive untrusted user input for glob patterns or environment variables.
-   - Release jobs operate only on the repository contents of this project plus standard CI-provided environment variables.
+   - The CI configuration and project scripts **never invoked the `glob` CLI** with the dangerous `-c/--cmd` flags.
+   - The semantic-release/npm toolchain did **not** receive untrusted user input for glob patterns or environment variables.
+   - Release jobs operated only on the repository contents of this project plus standard CI-provided environment variables.
 
 4. **Audit and Monitoring**
-   - Dev-only vulnerabilities are tracked via `npm run audit:dev-high`, which writes a machine-readable report to `ci/npm-audit.json` for each CI run.
-   - `dry-aged-deps` reports (`ci/dry-aged-deps.json`) are stored as CI artifacts to document when no safe upgrade path exists under the configured thresholds.
-   - A nightly `dependency-health` workflow re-runs dev-dependency audits to keep this risk under continuous review.
+   - Dev-only vulnerabilities were tracked via `npm run audit:dev-high`, which wrote a machine-readable report to `ci/npm-audit.json` for each CI run.
+   - `dry-aged-deps` reports (`ci/dry-aged-deps.json`) were stored as CI artifacts to document when no safe upgrade path existed under the configured thresholds.
+   - A nightly `dependency-health` workflow re-ran dev-dependency audits to keep this type of risk under continuous review.
 
 5. **Guarded semantic-release Invocation (CI-Only)**
-   - semantic-release is invoked **only from CI**, and guarded to ensure it runs under the intended safe context (GitHub Actions, push to `main`, CI environment).
-   - Local developers are not expected to run semantic-release directly; publishing is handled automatically by CI after all quality and security checks pass.
-
-### Upgrade Plan
-
-We intend to migrate away from the affected semantic-release/npm toolchain as soon as a safe, dry‑aged‑deps–approved upgrade path is available:
-
-1. Continue monitoring `dry-aged-deps` output for `@semantic-release/npm`, `semantic-release`, and related packages.
-2. When a newer, vulnerability-free version remains stable for at least 7 days and passes our audit checks, update the dev dependencies accordingly.
-3. After migration, convert the existing known-error record into a resolved incident that documents the fix and new baseline.
+   - semantic-release was invoked **only from CI**, and guarded to ensure it ran under the intended safe context (GitHub Actions, push to `main`, CI environment).
+   - Local developers were not expected to run semantic-release directly; publishing was handled automatically by CI after all quality and security checks passed.
 
-Until then, the risk remains **limited to CI release automation** and does not change the guarantees we provide for production dependencies or end-user environments.
+With the upgraded release toolchain, these controls continue to constrain dev-only tooling and help ensure that vulnerabilities in CI infrastructure do not impact the security properties of the published package.
 
 ---
 

package/lib/src/maintenance/cli.js

@@ -18,10 +18,8 @@ function runMaintenanceCli(rawArgv) {
     const initialNormalized = (0, flags_1.normalizeCliArgs)(rawArgv);
     const { subcommand: command } = initialNormalized;
     if (!command || command === "-h" || command === "--help") {
-        /**
-         * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-         * @req REQ-MAINT-SAFE - Handle help requests safely and provide discoverable usage output
-         */
+        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
+        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Branch to show usage when no command or help flag is provided; handle help requests safely and provide discoverable usage output
         printHelp();
         return commands_1.EXIT_OK;
     }
@@ -29,37 +27,36 @@ function runMaintenanceCli(rawArgv) {
     // receive the subcommand name and its raw argument vector unchanged.
     const normalized = initialNormalized;
     try {
+        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
+        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Catch unexpected errors and surface concise diagnostics without crashing
         switch (command) {
             case "detect":
-                // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md @req REQ-MAINT-DETECT - Dispatch to detection handler
+                // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT - Branch to dispatch to detection handler when 'detect' is requested; dispatch to detection handler
                 return (0, commands_1.handleDetect)(normalized);
             case "verify":
-                // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md @req REQ-MAINT-VERIFY - Dispatch to verification handler
+                // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-VERIFY - Branch to dispatch to verification handler when 'verify' is requested; dispatch to verification handler
                 return (0, commands_1.handleVerify)(normalized);
             case "report":
-                // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md @req REQ-MAINT-REPORT - Dispatch to reporting handler
+                // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-REPORT - Branch to dispatch to reporting handler when 'report' is requested; dispatch to reporting handler
                 return (0, commands_1.handleReport)(normalized);
             case "update": {
-                // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md @req REQ-MAINT-UPDATE - Dispatch to update handler
+                // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE - Branch to dispatch to update handler when 'update' is requested; dispatch to update handler
                 const result = (0, commands_1.handleUpdate)(normalized);
-                // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md @req REQ-MAINT-SAFE - Print help on usage errors from update
                 if (result === commands_1.EXIT_USAGE) {
+                    // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Print help on usage errors from update; help branch for update usage errors
                     printHelp();
                 }
                 return result;
             }
             default:
-                // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md @req REQ-MAINT-SAFE - Handle unknown commands safely with diagnostics
+                // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Branch for unknown commands to emit diagnostics and safe usage guidance; handle unknown commands safely with diagnostics
                 console.error(`Unknown command: ${command}`);
                 printHelp();
                 return commands_1.EXIT_USAGE;
         }
     }
     catch (error) {
-        /**
-         * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-         * @req REQ-MAINT-SAFE - Catch unexpected errors and surface concise diagnostics without crashing
-         */
+        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Catch-all error branch to prevent crashes and provide concise diagnostics; catch unexpected errors and surface concise diagnostics without crashing
         const message = error instanceof Error
             ? error.message
             : "Unknown error in maintenance CLI";
@@ -73,8 +70,7 @@ function runMaintenanceCli(rawArgv) {
  * @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
+    // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Help branch ensures users can discover maintenance CLI usage safely; provide discoverable CLI usage information
     console.log(`traceability-maint - Traceability annotation maintenance tools
 
 Usage:

package/lib/src/maintenance/detect.js

@@ -54,6 +54,9 @@ function detectStaleAnnotations(codebasePath) {
     // @req REQ-MAINT-DETECT - Return empty result if workspaceRoot does not exist or is not a directory
     if (!fs.existsSync(workspaceRoot) ||
         !fs.statSync(workspaceRoot).isDirectory()) {
+        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
+        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
+        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
         return [];
     }
     const stale = new Set();
@@ -76,9 +79,12 @@ function processFileForStaleAnnotations(file, workspaceRoot, cwd, stale) {
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
     // @req REQ-MAINT-DETECT - Handle file read errors gracefully
     try {
+        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
         content = fs.readFileSync(file, "utf8");
     }
     catch {
+        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
+        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Swallow file read failures without aborting detection
         return;
     }
     const regex = /@story\s+([^\s]+)/g;
@@ -97,6 +103,7 @@ 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
     if ((0, storyReferenceUtils_1.isUnsafeStoryPath)(storyPath)) {
+        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
         return;
     }
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
@@ -108,6 +115,7 @@ function handleStoryMatch(storyPath, workspaceRoot, cwd, stale) {
     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) {
+        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT - No in-project candidates means nothing to check or mark stale
         return;
     }
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
@@ -116,6 +124,7 @@ function handleStoryMatch(storyPath, workspaceRoot, cwd, stale) {
     // @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) {
+        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
         stale.add(storyPath);
     }
 }
@@ -127,18 +136,24 @@ function getInProjectCandidates(storyProjectCandidate, storyCodebaseCandidate, w
     let projectBoundary;
     let codebaseBoundary;
     try {
+        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
         projectBoundary = (0, storyReferenceUtils_1.enforceProjectBoundary)(storyProjectCandidate, workspaceRoot);
     }
     catch {
+        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
+        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Treat boundary enforcement failures as out-of-project
         projectBoundary = {
             isWithinProject: false,
             candidate: storyProjectCandidate,
         };
     }
     try {
+        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
         codebaseBoundary = (0, storyReferenceUtils_1.enforceProjectBoundary)(storyCodebaseCandidate, workspaceRoot);
     }
     catch {
+        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
+        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Treat boundary enforcement failures as out-of-project
         codebaseBoundary = {
             isWithinProject: false,
             candidate: storyCodebaseCandidate,
@@ -146,9 +161,11 @@ function getInProjectCandidates(storyProjectCandidate, storyCodebaseCandidate, w
     }
     const inProjectCandidates = [];
     if (projectBoundary.isWithinProject) {
+        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT - Collect project-relative in-project candidate
         inProjectCandidates.push(projectBoundary.candidate);
     }
     if (codebaseBoundary.isWithinProject) {
+        // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT - Collect workspace-root-relative in-project candidate
         inProjectCandidates.push(codebaseBoundary.candidate);
     }
     return inProjectCandidates;
@@ -158,5 +175,15 @@ function getInProjectCandidates(storyProjectCandidate, storyCodebaseCandidate, w
  * @req REQ-MAINT-DETECT - Check on-disk existence of in-project candidates
  */
 function anyInProjectCandidateExists(inProjectCandidates) {
-    return inProjectCandidates.some((p) => fs.existsSync(p));
+    return inProjectCandidates.some(
+    /**
+     * @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-SAFE
+     */
+    (p) => {
+        const exists = fs.existsSync(p);
+        if (!exists) {
+            // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - Safely handle non-existent candidate without throwing
+        }
+        return exists;
+    });
 }

package/lib/src/rules/helpers/require-story-io.d.ts

@@ -29,10 +29,10 @@ export declare function linesBeforeHasStory(sourceCode: any, node: any, lookback
 export declare function parentChainHasStory(sourceCode: any, node: any): boolean;
 /**
  * Fallback: inspect text immediately preceding the node in sourceCode.getText to find @story
- * Also accepts @implements annotations as satisfying story presence for this rule.
+ * Also accepts @supports annotations as satisfying story presence for this rule.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-ANNOTATION-REQUIRED - Provide fallback textual inspection when other heuristics fail
- * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Treat @implements annotations as satisfying story presence in fallback checks
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Treat @supports annotations as satisfying story presence in fallback checks
  */
 export declare function fallbackTextBeforeHasStory(sourceCode: any, node: any): boolean;

package/lib/src/rules/helpers/require-story-io.js

@@ -23,17 +23,17 @@ exports.LOOKBACK_LINES = 4;
 exports.FALLBACK_WINDOW = 800;
 /**
  * Shared predicate to determine if a given comment node contains an @story marker.
- * Also treats @implements annotations as satisfying story presence checks.
+ * Also treats @supports annotations as satisfying story presence checks.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-ANNOTATION-REQUIRED - Centralize @story detection logic for comment value inspection
- * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Treat @implements annotations as satisfying story presence checks
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Treat @supports annotations as satisfying story presence checks
  */
 function commentContainsStory(comment) {
     if (typeof comment?.value !== "string") {
         return false;
     }
-    return (comment.value.includes("@story") || comment.value.includes("@implements"));
+    return (comment.value.includes("@story") || comment.value.includes("@supports"));
 }
 /**
  * Safely extract the physical source lines array from sourceCode for scanning.
@@ -61,20 +61,20 @@ function getNodeStartLine(node) {
  * Generic helper to scan a range of physical source lines for the presence of an @story marker.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED - Reuse line scanning logic for story annotations across helpers
- * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @implements annotations as valid markers during line scanning
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @supports annotations as valid markers during line scanning
  */
 function scanLinesForMarker(lines, from, to) {
-    // Walk each physical line in the configured lookback window to search for an inline @story or @implements marker.
+    // Walk each physical line in the configured lookback window to search for an inline @story or @supports marker.
     // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
     // @req REQ-ANNOTATION-REQUIRED - Scan preceding lines for existing story annotations
     for (let i = from; i < to; i++) {
         const text = lines[i];
-        // Treat any line containing "@story" or "@implements" as evidence that the function is already annotated.
+        // Treat any line containing "@story" or "@supports" as evidence that the function is already annotated.
         // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
         // @req REQ-ANNOTATION-REQUIRED - Detect explicit @story markers in raw source text
-        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Detect explicit @implements markers in raw source text
+        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Detect explicit @supports markers in raw source text
         if (typeof text === "string" &&
-            (text.includes("@story") || text.includes("@implements"))) {
+            (text.includes("@story") || text.includes("@supports"))) {
             return true;
         }
     }
@@ -134,11 +134,11 @@ function parentChainHasStory(sourceCode, node) {
 }
 /**
  * Fallback: inspect text immediately preceding the node in sourceCode.getText to find @story
- * Also accepts @implements annotations as satisfying story presence for this rule.
+ * Also accepts @supports annotations as satisfying story presence for this rule.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-ANNOTATION-REQUIRED - Provide fallback textual inspection when other heuristics fail
- * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Treat @implements annotations as satisfying story presence in fallback checks
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Treat @supports annotations as satisfying story presence in fallback checks
  */
 function fallbackTextBeforeHasStory(sourceCode, node) {
     // Skip fallback text inspection when the sourceCode API or node range information is not available.
@@ -161,12 +161,12 @@ function fallbackTextBeforeHasStory(sourceCode, node) {
         // @req REQ-ANNOTATION-REQUIRED - Restrict fallback text scanning to a safe, fixed-size window
         const start = Math.max(0, range[0] - exports.FALLBACK_WINDOW);
         const textBefore = sourceCode.getText().slice(start, range[0]);
-        // Detect any @story or @implements marker that appears within the bounded fallback window.
+        // Detect any @story or @supports marker that appears within the bounded fallback window.
         // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
         // @req REQ-ANNOTATION-REQUIRED - Recognize story annotations discovered via fallback text scanning
-        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Recognize @implements annotations discovered via fallback text scanning
+        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Recognize @supports annotations discovered via fallback text scanning
         if (typeof textBefore === "string" &&
-            (textBefore.includes("@story") || textBefore.includes("@implements"))) {
+            (textBefore.includes("@story") || textBefore.includes("@supports"))) {
             return true;
         }
     }

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

@@ -7,7 +7,7 @@
  * @req REQ-MULTILINE-SUPPORT - Handle annotations split across multiple lines
  * @req REQ-FLEXIBLE-PARSING - Support reasonable variations in whitespace and formatting
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
- * @req REQ-IMPLEMENTS-PARSE - Parse @implements annotations without affecting @story/@req
+ * @req REQ-SUPPORTS-PARSE - Parse @supports annotations without affecting @story/@req
  * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
  */
 /**
@@ -24,7 +24,7 @@ export interface PendingAnnotation {
  * This function trims whitespace, keeps any annotation tags that appear
  * later in the line, and supports common JSDoc styles such as leading "*".
  *
- * It detects @story, @req, and @implements tags while preserving the rest
+ * It detects @story, @req, and @supports tags while preserving the rest
  * of the line for downstream logic.
  */
 export declare function normalizeCommentLine(rawLine: string): string;

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

@@ -8,7 +8,7 @@
  * @req REQ-MULTILINE-SUPPORT - Handle annotations split across multiple lines
  * @req REQ-FLEXIBLE-PARSING - Support reasonable variations in whitespace and formatting
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
- * @req REQ-IMPLEMENTS-PARSE - Parse @implements annotations without affecting @story/@req
+ * @req REQ-SUPPORTS-PARSE - Parse @supports annotations without affecting @story/@req
  * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
  */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -19,7 +19,7 @@ exports.normalizeCommentLine = normalizeCommentLine;
  * This function trims whitespace, keeps any annotation tags that appear
  * later in the line, and supports common JSDoc styles such as leading "*".
  *
- * It detects @story, @req, and @implements tags while preserving the rest
+ * It detects @story, @req, and @supports tags while preserving the rest
  * of the line for downstream logic.
  */
 function normalizeCommentLine(rawLine) {
@@ -27,7 +27,7 @@ function normalizeCommentLine(rawLine) {
     if (!trimmed) {
         return "";
     }
-    const annotationMatch = trimmed.match(/@story\b|@req\b|@implements\b/);
+    const annotationMatch = trimmed.match(/@story\b|@req\b|@supports\b/);
     if (!annotationMatch || annotationMatch.index === undefined) {
         const withoutLeadingStar = trimmed.replace(/^\*\s?/, "");
         return withoutLeadingStar;

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

@@ -42,7 +42,10 @@ export declare function collapseAnnotationValue(value: string): string;
  *
  * Returns the fixed path when safe, or null if no fix should be applied.
  *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md
+ * @story docs/stories/010.2-REQ-STORY-PATH-AUTOFIX.story.md
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  * @req REQ-AUTOFIX-SAFE - Auto-fix must be conservative and never broaden the referenced path
  * @req REQ-AUTOFIX-PRESERVE - Preserve surrounding formatting when normalizing story path suffixes
@@ -53,6 +56,7 @@ export declare function getFixedStoryPath(original: string): string | null;
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md
  * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  */
@@ -62,6 +66,7 @@ export declare function buildStoryErrorMessage(kind: "missing" | "invalid", valu
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md
  * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  */