eslint-plugin-traceability 1.7.1 → 1.8.1

package/CHANGELOG.md

@@ -0,0 +1,82 @@
+## [1.8.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.8.0...v1.8.1) (2025-12-04)
+
+
+### Bug Fixes
+
+* disable prefer-implements-annotation in default presets ([89c62e9](https://github.com/voder-ai/eslint-plugin-traceability/commit/89c62e907be95030f89e6a3ab6df24a4ba32ab62))
+
+# Changelog
+
+This project uses automated release management via [semantic-release](https://semantic-release.gitbook.io/).
+
+For detailed release notes and changelog information, please see:
+
+**[GitHub Releases](https://github.com/voder-ai/eslint-plugin-traceability/releases)**
+
+Each release includes:
+- Detailed change descriptions
+- Commit references
+- Breaking changes (if any)
+- Migration notes (when applicable)
+
+---
+
+## Historical Changelog (Prior to Automated Releases)
+
+The following entries were maintained manually before the adoption of semantic-release. Current and future releases are documented exclusively on the GitHub Releases page.
+
+### [1.0.5] - 2025-11-17
+
+**Changed**
+- Lowered maintainability thresholds to 70 lines/function and 300 lines/file in ESLint config.
+- Added override for 'tar' package to mitigate moderate vulnerabilities.
+
+### [1.0.4] - 2025-11-17
+
+**Fixed**
+- Ensured temporary directories are cleaned up in maintenance tests for detect and update functions.
+- Refactored valid-req-reference rule to reduce function length and added explicit type annotations.
+
+### [1.0.3] - 2025-11-17
+
+**Added**
+- CLI integration script (`cli-integration.js`) for end-to-end ESLint CLI tests.
+- Migration guide in [`user-docs/migration-guide.md`](user-docs/migration-guide.md).
+
+### [1.0.2] - 2025-11-17
+
+**Changed**
+- Updated README and docs to reference `cli-integration.js` script.
+- Removed stale references to migration guide in CHANGELOG gradients.
+
+### [1.0.1] - 2025-11-17
+
+**Added**
+- Detailed API documentation in [`user-docs/api-reference.md`](user-docs/api-reference.md)
+- New usage examples in [`user-docs/examples.md`](user-docs/examples.md)
+
+**Changed**
+- Updated `README.md` with advanced usage instructions and migration guide
+- Consolidated CI workflows into a unified GitHub Actions pipeline
+
+### [1.0.0] - 2025-11-16
+
+**Changed**
+- Bumped version to 1.0.0 in package.json.
+- Aligned CHANGELOG with package.json version.
+
+### [0.1.0] - 2025-11-16
+
+**Added**
+- Initial release of `eslint-plugin-traceability`:
+  - `require-story-annotation`
+  - `require-req-annotation`
+  - `require-branch-annotation`
+  - `valid-annotation-format`
+  - `valid-story-reference`
+  - `valid-req-reference`
+- Documentation for all rules under `docs/rules`.
+- Configuration presets in `docs/config-presets.md`.
+- 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

@@ -15,7 +15,7 @@ Prerequisites: Node.js >=18.18.0 and ESLint v9+.
 2. Using Yarn  
    yarn add --dev eslint-plugin-traceability
 
-For detailed setup with ESLint v9, see user-docs/eslint-9-setup-guide.md.
+For detailed setup with ESLint v9, see the [ESLint v9 Setup Guide](user-docs/eslint-9-setup-guide.md).
 
 ## Usage
 
@@ -26,39 +26,39 @@ Additional ESLint v9 configuration guidance:
 - For detailed configuration examples, see [Common Configuration Patterns](user-docs/eslint-9-setup-guide.md#common-configuration-patterns) in the ESLint 9 Setup Guide.
 - For troubleshooting ESLint flat-config errors, see [Troubleshooting ESLint Configuration](user-docs/eslint-9-setup-guide.md#troubleshooting-eslint-configuration).
 
-Example eslint.config.js (ESLint v9 flat config):
+Example `eslint.config.js` (ESLint v9 flat config):
+
+This example shows the recommended starting point using the plugin's recommended preset alongside ESLint's recommended config:
 
 ```js
 // eslint.config.js
-module.exports = [
+import js from "@eslint/js";
+import traceability from "eslint-plugin-traceability";
+
+export default [
+  js.configs.recommended,
   {
-    env: {
-      es2021: true,
-      node: true,
-    },
-    plugins: { traceability: {} },
-    rules: {
-      "traceability/require-story-annotation": "error",
-      "traceability/require-req-annotation": "error",
-      "traceability/require-branch-annotation": "error",
+    plugins: {
+      traceability,
     },
   },
+  ...traceability.configs.recommended,
 ];
 ```
 
 ### Available Rules
 
-- `traceability/require-story-annotation` Enforces presence of `@story` annotations. ([Documentation](docs/rules/require-story-annotation.md))
-- `traceability/require-req-annotation` Enforces presence of `@req` annotations. ([Documentation](docs/rules/require-req-annotation.md))
-- `traceability/require-branch-annotation` Enforces presence of branch annotations. ([Documentation](docs/rules/require-branch-annotation.md))
-- `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))
+- `traceability/require-story-annotation` Enforces presence of `@story` annotations. (See the rule documentation in the plugin's user guide.)
+- `traceability/require-req-annotation` Enforces presence of `@req` annotations. (See the rule documentation in the plugin's user guide.)
+- `traceability/require-branch-annotation` Enforces presence of branch annotations. (See the rule documentation in the plugin's user guide.)
+- `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.)
 
-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).
+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).
 
-For development and contribution guidelines, see docs/eslint-plugin-development-guide.md.
+For development and contribution guidelines, see the contribution guide in the repository.
 
 ## Quick Start
 
@@ -69,8 +69,12 @@ For development and contribution guidelines, see docs/eslint-plugin-development-
 import traceability from "eslint-plugin-traceability";
 
 export default [
-  // Load the traceability plugin's recommended rule set
-  traceability.configs.recommended,
+  {
+    plugins: {
+      traceability,
+    },
+  },
+  ...traceability.configs.recommended,
 ];
 ```
 
@@ -78,7 +82,8 @@ export default [
 
 ```js
 /**
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ *   // Point this to your own project's story/requirements file, not to this plugin's internal docs.
  * @req REQ-ANNOTATION-REQUIRED
  */
 function initAuth() {
@@ -188,18 +193,52 @@ npm test
 
 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.
+
+### What end users can expect from production dependencies
+
+- The published `eslint-plugin-traceability` package is intended to ship **only with production dependencies that have no known high‑severity vulnerabilities** at release time.
+- As part of CI and the local pre‑push hook, we run:
+  - `npm audit --omit=dev --audit-level=high` – this checks only the **runtime (prod) dependency graph** and fails if any high‑severity issues are reported.
+- This means:
+  - Known high‑severity issues in production dependencies are blocked before a version is released.
+  - Dev‑only tooling and CI infrastructure are kept separate from what you install via `npm install eslint-plugin-traceability`.
+
+### How `dry-aged-deps` and `npm audit` work together
+
+- **Maturity checks via `dry-aged-deps`**
+  - We use `dry-aged-deps` (via `npm run deps:maturity` and `npm run safety:deps`) to enforce basic “maturity” constraints on dependency updates.
+  - Current policy for adopting new versions:
+    - **Minimum age:** new versions are typically required to be **at least 7 days old**, reducing the chance of adopting a just‑released, unvetted version.
+    - **No known vulnerabilities:** versions with known vulnerabilities are rejected.
+- **Security scan via `npm audit`**
+  - `npm audit --omit=dev --audit-level=high` is run on the **production dependency tree** to catch known high‑severity issues before release.
+- **Combined effect**
+  - `dry-aged-deps` controls **which versions** we are willing to upgrade to (age + no‑known‑vulns).
+  - `npm audit` validates that the **current, locked set of production dependencies** is free from known high‑severity vulnerabilities.
+  - Together, they provide a conservative, security‑focused process for dependency updates that directly affect end users.
+
+### Scope of the semantic‑release/npm tooling risk
+
+- There is a known, documented risk in the semantic‑release/npm release toolchain related to bundled `npm`/`glob`/`brace-expansion`.
+- This risk:
+  - Applies only to the **GitHub Actions release workflow and related dev‑only tooling**.
+  - Does **not** modify or run inside consumers’ projects.
+  - Does **not** affect the built plugin artifacts published to npm.
+- In other words:
+  - The issue is confined to the CI environment that prepares and publishes releases.
+  - It **cannot impact** the runtime behavior or dependency graph of the `eslint-plugin-traceability` package you install or use in your own projects.
+
 ## Documentation Links
 
-- ESLint v9 Setup Guide: user-docs/eslint-9-setup-guide.md
-- Plugin Development Guide: docs/eslint-plugin-development-guide.md
-- API Reference: user-docs/api-reference.md
-- Examples: user-docs/examples.md
-- Migration Guide: user-docs/migration-guide.md
-- Full README: https://github.com/voder-ai/eslint-plugin-traceability#readme
-- Rule: require-story-annotation: docs/rules/require-story-annotation.md
-- Rule: require-req-annotation: docs/rules/require-req-annotation.md
-- Rule: require-branch-annotation: docs/rules/require-branch-annotation.md
-- Contribution guide: https://github.com/voder-ai/eslint-plugin-traceability/blob/main/CONTRIBUTING.md
-- Issue tracker: https://github.com/voder-ai/eslint-plugin-traceability/issues
-- Configuration Presets: docs/config-presets.md
-- Changelog: CHANGELOG.md
+- ESLint v9 Setup Guide: [user-docs/eslint-9-setup-guide.md](user-docs/eslint-9-setup-guide.md)
+- API Reference: [user-docs/api-reference.md](user-docs/api-reference.md)
+- Examples: [user-docs/examples.md](user-docs/examples.md)
+- Migration Guide: [user-docs/migration-guide.md](user-docs/migration-guide.md)
+- Full README: <https://github.com/voder-ai/eslint-plugin-traceability#readme>
+- Contribution guide: <https://github.com/voder-ai/eslint-plugin-traceability/blob/main/CONTRIBUTING.md>
+- Issue tracker: <https://github.com/voder-ai/eslint-plugin-traceability/issues>
+- Changelog: [CHANGELOG.md](CHANGELOG.md)
+- Versioning and Releases: This project uses semantic-release for automated versioning. The authoritative list of published versions and release notes is on GitHub Releases: <https://github.com/voder-ai/eslint-plugin-traceability/releases>

package/SECURITY.md

@@ -0,0 +1,132 @@
+# Security Policy
+
+This document describes how security is handled for `eslint-plugin-traceability`, including how to report vulnerabilities, what guarantees apply to production dependencies, and how we manage known risks in our dev-only release tooling.
+
+> This file is **user-facing** documentation. Internal implementation details and deeper discussion live in the project’s internal documentation and decision records.
+
+## Reporting a Vulnerability
+
+If you believe you have found a security vulnerability in this project:
+
+1. **Do not open a public GitHub issue.**
+2. Instead, open a private security advisory via the GitHub Security tab for this repository:
+   - Navigate to: `Security` → `Advisories` → `Report a vulnerability`.
+3. Provide as much detail as you can (steps to reproduce, impact, affected environments). A maintainer will review and coordinate a fix and disclosure timeline with you.
+
+If you cannot use GitHub Security Advisories, you may alternatively open a **minimal** issue that does not disclose details and ask for a private contact channel.
+
+## Supported Versions
+
+This project uses [semantic-release](https://github.com/semantic-release/semantic-release) for automated versioning and publishing.
+
+- The **latest published version** on npm and GitHub Releases is considered supported.
+- Older versions are not actively maintained; security fixes are applied to the current release line and then published automatically.
+- To benefit from security fixes, users should stay reasonably up-to-date with the latest versions of `eslint-plugin-traceability`.
+
+Authoritative release information is available on GitHub Releases:
+
+- <https://github.com/voder-ai/eslint-plugin-traceability/releases>
+
+## Production Dependency Guarantees
+
+The `eslint-plugin-traceability` package has **no runtime dependencies**; it ships only its compiled plugin and CLI code plus documentation. Nevertheless, we treat any future production dependencies with care and enforce the following guarantees at release time:
+
+- Before a release is published, CI runs:
+  - `npm audit --omit=dev --audit-level=high`
+- A release is allowed to proceed only when:
+  - There are **no known high-severity vulnerabilities** reported in the **production (runtime) dependency tree**.
+
+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.
+
+## Dependency Maturity and `dry-aged-deps`
+
+In addition to `npm audit`, we use [`dry-aged-deps`](https://github.com/voder-ai/dry-aged-deps) to guide dependency upgrades for both production and development dependencies.
+
+Current high-level policy:
+
+- **Minimum age:** new versions are generally required to be **at least 7 days old** before adoption.
+- **No known vulnerabilities:** versions with _any_ known vulnerability (even low severity) are not considered "safe" upgrade candidates.
+
+`dry-aged-deps` is advisory only:
+
+- It does **not** modify `package.json` or install anything automatically.
+- It produces machine-readable reports that are stored as CI artifacts and referenced in internal security/incident documentation.
+
+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.
+
+## 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.
+
+### What is affected?
+
+- 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:
+  - `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.
+
+### What is _not_ affected?
+
+- The published `eslint-plugin-traceability` package has **no runtime dependencies** on this 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.
+
+### Why is this risk currently accepted?
+
+Under our `dry-aged-deps` policy (7‑day minimum age, no known vulnerabilities):
+
+- 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.
+
+This acceptance is documented in detail in the project’s internal security incident records and architectural decision records.
+
+### Compensating Controls
+
+To keep this dev-only risk tightly contained, we apply several compensating controls:
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+---
+
+## Attribution
+
+Created autonomously by [voder.ai](https://voder.ai).

package/lib/src/index.d.ts

@@ -17,6 +17,11 @@ import { detectStaleAnnotations, updateAnnotationReferences, batchUpdateAnnotati
 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>;
+declare const plugin: {
+    rules: typeof rules;
+    configs?: unknown;
+    maintenance?: unknown;
+};
 /**
  * @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)
@@ -25,17 +30,11 @@ declare const rules: Record<RuleName, Rule.RuleModule>;
  */
 declare const configs: {
     recommended: {
-        plugins: {
-            traceability: {};
-        };
         rules: {
             [x: string]: "error" | "warn";
         };
     }[];
     strict: {
-        plugins: {
-            traceability: {};
-        };
         rules: {
             [x: string]: "error" | "warn";
         };
@@ -53,32 +52,4 @@ declare const maintenance: {
     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" | "prefer-implements-annotation", Rule.RuleModule>;
-    configs: {
-        recommended: {
-            plugins: {
-                traceability: {};
-            };
-            rules: {
-                [x: string]: "error" | "warn";
-            };
-        }[];
-        strict: {
-            plugins: {
-                traceability: {};
-            };
-            rules: {
-                [x: string]: "error" | "warn";
-            };
-        }[];
-    };
-    maintenance: {
-        detectStaleAnnotations: typeof detectStaleAnnotations;
-        updateAnnotationReferences: typeof updateAnnotationReferences;
-        batchUpdateAnnotations: typeof batchUpdateAnnotations;
-        verifyAnnotations: typeof verifyAnnotations;
-        generateMaintenanceReport: typeof generateMaintenanceReport;
-    };
-};
-export default _default;
+export default plugin;

package/lib/src/index.js

@@ -73,6 +73,9 @@ RULE_NAMES.forEach(
         };
     }
 });
+const plugin = {
+    rules,
+};
 /**
  * @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)
@@ -86,18 +89,16 @@ const TRACEABILITY_RULE_SEVERITIES = {
     "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)
+ * @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
  */
 function createTraceabilityFlatConfig() {
     return {
-        plugins: {
-            traceability: {},
-        },
         rules: {
             ...TRACEABILITY_RULE_SEVERITIES,
         },
@@ -114,6 +115,7 @@ const configs = {
     strict: [createTraceabilityFlatConfig()],
 };
 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
@@ -126,4 +128,5 @@ const maintenance = {
     generateMaintenanceReport: maintenance_1.generateMaintenanceReport,
 };
 exports.maintenance = maintenance;
-exports.default = { rules, configs, maintenance };
+plugin.maintenance = maintenance;
+exports.default = plugin;

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

@@ -3,6 +3,9 @@
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-BATCH - Perform batch updates
  * @req REQ-MAINT-VERIFY - Verify annotation references
+ * @param codebasePath Absolute path to the workspace root where annotations will be updated.
+ * @param mappings Array of mapping objects describing path changes, each containing an oldPath and newPath.
+ * @returns Total number of updated @story annotations across all mappings.
  */
 export declare function batchUpdateAnnotations(codebasePath: string, mappings: {
     oldPath: string;
@@ -12,5 +15,7 @@ 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
+ * @param codebasePath Absolute path to the workspace root whose annotations should be verified.
+ * @returns Boolean indicating whether there are no stale annotations remaining (true if clean, false if any remain).
  */
 export declare function verifyAnnotations(codebasePath: string): boolean;

package/lib/src/maintenance/batch.js

@@ -9,6 +9,9 @@ const detect_1 = require("./detect");
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-BATCH - Perform batch updates
  * @req REQ-MAINT-VERIFY - Verify annotation references
+ * @param codebasePath Absolute path to the workspace root where annotations will be updated.
+ * @param mappings Array of mapping objects describing path changes, each containing an oldPath and newPath.
+ * @returns Total number of updated @story annotations across all mappings.
  */
 function batchUpdateAnnotations(codebasePath, mappings) {
     let totalUpdated = 0;
@@ -22,6 +25,8 @@ function batchUpdateAnnotations(codebasePath, 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
+ * @param codebasePath Absolute path to the workspace root whose annotations should be verified.
+ * @returns Boolean indicating whether there are no stale annotations remaining (true if clean, false if any remain).
  */
 function verifyAnnotations(codebasePath) {
     const staleAnnotations = (0, detect_1.detectStaleAnnotations)(codebasePath);