eslint-plugin-traceability 1.7.1 → 1.8.0

package/CHANGELOG.md

@@ -0,0 +1,82 @@
+# [1.8.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.7.1...v1.8.0) (2025-12-03)
+
+
+### Features
+
+* accept [@implements](https://github.com/implements) annotations in require rules ([bdf0994](https://github.com/voder-ai/eslint-plugin-traceability/commit/bdf0994f0d0e16bd751fbd89c08c67bddee52c16))
+
+# 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,24 +26,16 @@ 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 = [
-  {
-    env: {
-      es2021: true,
-      node: true,
-    },
-    plugins: { traceability: {} },
-    rules: {
-      "traceability/require-story-annotation": "error",
-      "traceability/require-req-annotation": "error",
-      "traceability/require-branch-annotation": "error",
-    },
-  },
-];
+import js from "@eslint/js";
+import traceability from "eslint-plugin-traceability";
+
+export default [js.configs.recommended, traceability.configs.recommended];
 ```
 
 ### Available Rules
@@ -56,9 +48,9 @@ module.exports = [
 - `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).
+Configuration options: For detailed per-rule options (such as scopes, branch types, and story directory settings), see the individual rule docs in [`docs/rules/`](docs/rules) 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 [ESLint Plugin Development Guide](docs/eslint-plugin-development-guide.md).
 
 ## Quick Start
 
@@ -78,7 +70,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 +181,65 @@ npm test
 
 These tests verify end-to-end behavior of the plugin via the ESLint CLI.
 
+## Security and Dependency Health
+
+### 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.
+
+### Optional deeper background
+
+For readers who want more context on the dependency and security model (not required to use the plugin):
+
+- Dependency health overview: [docs/dependency-health.md](docs/dependency-health.md)
+- Detailed incident note about the semantic‑release/npm toolchain risk:  
+  [docs/security-incidents/SECURITY-INCIDENT-2025-11-18-semantic-release-bundled-npm.known-error.md](docs/security-incidents/SECURITY-INCIDENT-2025-11-18-semantic-release-bundled-npm.known-error.md)
+
+These documents are informational and describe internal processes and known toolchain limitations; they do not change the guarantees described above for end users.
+
 ## 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)
+- Plugin Development Guide: [docs/eslint-plugin-development-guide.md](docs/eslint-plugin-development-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>
+- Rule: require-story-annotation: [docs/rules/require-story-annotation.md](docs/rules/require-story-annotation.md)
+- Rule: require-req-annotation: [docs/rules/require-req-annotation.md](docs/rules/require-req-annotation.md)
+- Rule: require-branch-annotation: [docs/rules/require-branch-annotation.md](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](docs/config-presets.md)
+- 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/docs/ci-cd-pipeline.md

@@ -0,0 +1,224 @@
+# CI/CD Pipeline and Continuous Deployment
+
+This document describes how continuous integration and continuous deployment are implemented for `eslint-plugin-traceability`, and how it relates to our architecture decisions.
+
+- Related ADRs:
+  - `docs/decisions/006-semantic-release-for-automated-publishing.accepted.md`
+  - `docs/decisions/007-github-releases-over-changelog.accepted.md`
+  - `docs/decisions/005-github-actions-validation-tooling.accepted.md`
+
+## Overview
+
+We use a **single unified GitHub Actions workflow** to run all quality checks and, on successful main-branch builds, to automatically publish new versions to npm and create GitHub Releases.
+
+- Workflow file: `.github/workflows/ci-cd.yml`
+- Workflow name: `CI/CD Pipeline`
+- Triggers:
+  - `push` to `main`
+  - `pull_request` targeting `main`
+  - Nightly `schedule` for dependency health checks
+
+There are no tag-based triggers and no manual `workflow_dispatch` jobs for releases. Publishing (when needed) always happens as part of the same workflow run that executes the quality gates.
+
+## Jobs
+
+### 1. `quality-and-deploy`
+
+Runs on:
+
+- Every `push` to `main`
+- Every `pull_request` targeting `main`
+
+Matrix:
+
+- Node `18.x`
+- Node `20.x`
+
+Key steps (in order):
+
+1. **Checkout & Node setup**
+   - `actions/checkout@v4` with full history (needed for semantic-release)
+   - `actions/setup-node@v4` with `cache: npm`
+
+2. **Script validation**
+   - `node scripts/validate-scripts-nonempty.js` ensures all npm scripts referenced by CI exist and are non-empty.
+
+3. **Install dependencies**
+   - `npm ci`
+
+4. **Full quality gate**
+   - `npm run ci-verify:full`
+   - This script is the canonical definition of our quality gates and is also used by the Husky pre-push hook.
+   - It runs, in order:
+     - `npm run check:traceability`
+     - `npm run safety:deps`
+     - `npm run audit:ci`
+     - `npm run build`
+     - `npm run type-check`
+     - `npm run lint-plugin-check`
+     - `npm run lint -- --max-warnings=0`
+     - `npm run duplication`
+     - `npm run test -- --coverage`
+     - `npm run format:check`
+     - `npm audit --omit=dev --audit-level=high`
+     - `npm run audit:dev-high`
+
+5. **Secret scanning**
+   - Only on Node `20.x` matrix entry: `npm run security:secrets` using secretlint.
+
+6. **Artifact upload**
+   - Always upload:
+     - `ci/dry-aged-deps.json`
+     - `ci/npm-audit.json`
+     - `scripts/traceability-report.md`
+     - `ci/` (Jest and audit artifacts)
+
+7. **Automated release (semantic-release)**
+
+   Conditional step:
+
+   ```yaml
+   if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' && matrix['node-version'] == '20.x' && success() }}
+   ```
+
+   - Runs `npx semantic-release` with:
+     - GitHub authentication via `GITHUB_TOKEN`
+     - npm authentication via `NPM_TOKEN`
+   - Configuration is in `.releaserc.json` and uses:
+     - `@semantic-release/commit-analyzer`
+     - `@semantic-release/release-notes-generator`
+     - `@semantic-release/changelog` (writes to `CHANGELOG.md` but we treat GitHub Releases as the user-facing source of truth per ADR 007)
+     - `@semantic-release/npm` (publishes to npm)
+     - `@semantic-release/github` (creates GitHub Releases)
+
+   Behavior:
+   - On each successful push to `main`, semantic-release:
+     - Analyzes commits since the last tag using **Conventional Commits** (see `docs/conventional-commits-guide.md`).
+     - Decides whether the release is `major`, `minor`, `patch`, or **no release**.
+     - If no relevant commits are found, it logs that no new release is needed and exits successfully.
+     - If a release is warranted:
+       - Publishes a new version to npm.
+       - Creates or updates `CHANGELOG.md`.
+       - Creates a Git tag and GitHub Release with generated notes.
+
+   - Safety behavior:
+     - If `NPM_TOKEN` is **not set**, the step logs a message and exits 0 with `new_release_published=false`.
+     - If semantic-release fails due to invalid npm token (`EINVALIDNPMTOKEN`) or OTP requirement (`EOTP`), the step logs a warning and exits 0, skipping publish but not failing CI.
+     - Any other semantic-release error fails the job.
+
+8. **Post-deployment smoke test**
+   - Runs only when semantic-release reports that a new release was published:
+
+   ```yaml
+   if: steps.semantic-release.outputs.new_release_published == 'true'
+   ```
+
+   - Executes:
+
+   ```bash
+   chmod +x scripts/smoke-test.sh
+   ./scripts/smoke-test.sh "${{ steps.semantic-release.outputs.new_release_version }}"
+   ```
+
+   - `scripts/smoke-test.sh`:
+     - For a published version: waits for the version to appear on npm, then
+       - Creates a temp project.
+       - Installs `eslint-plugin-traceability@<version>`.
+       - Verifies the plugin loads and the installed version matches.
+       - Runs a minimal ESLint config using the plugin to confirm it can be loaded.
+
+### 2. `dependency-health`
+
+Runs only on the nightly `schedule` event.
+
+- Checks out code and installs dependencies.
+- Runs `npm run audit:dev-high` to generate a JSON report of high-severity dev-only vulnerabilities.
+- Does **not** publish or run semantic-release.
+
+This job is intentionally isolated from the main quality-and-deploy path and has no effect on releases.
+
+## Continuous Deployment Behavior
+
+- Every push to `main` triggers the `quality-and-deploy` job on Node 18.x and 20.x.
+- The full quality gate (`ci-verify:full`) must pass on both Node versions.
+- If, and only if, the Node 20.x job on `main` succeeds and `NPM_TOKEN` is available, semantic-release is invoked.
+- semantic-release decides whether a new version is required based on commit messages:
+  - `feat` → minor version bump
+  - `fix` → patch bump
+  - `feat!` or `BREAKING CHANGE:` footer → major bump
+  - Other types (`docs`, `chore`, `refactor`, `test`, `ci`, etc.) do **not** trigger a release.
+- When a release is published, the smoke test runs immediately in the same workflow execution.
+
+There is no separate “publish only” workflow and no manual tagging step required to release. The pipeline from commit → quality gates → publish → smoke test is fully automated.
+
+## Local Workflow and Hooks
+
+To keep local development aligned with CI:
+
+- **Pre-commit** (`.husky/pre-commit`):
+  - Runs `npx lint-staged`, which executes Prettier and ESLint with `--fix` on staged files in `src/` and `tests/`.
+- **Pre-push** (`.husky/pre-push`):
+  - Runs `npm run ci-verify:full`.
+  - This mirrors the CI quality gate so that most issues are caught before code reaches GitHub.
+  - Secret scanning (`npm run security:secrets`) currently runs only in CI on the Node 20.x matrix entry and is not part of the pre-push hook, but it uses the same configuration so results stay consistent between local and CI.
+
+Local verification commands:
+
+- `npm run ci-verify:full`
+  - Runs the same broad, end-to-end quality gate used in CI (build, type-check, linting, duplication checks, full Jest test suite with coverage, audits, and formatting checks).
+  - This is the closest approximation to the CI pipeline and is what the pre-push hook enforces.
+
+- `npm run ci-verify:fast`
+  - Runs a **narrower, targeted subset** of checks focused on the rule and maintenance test suites.
+  - Uses Jest with:
+
+    ```bash
+    jest --testPathPatterns 'tests/(rules|maintenance)'
+    ```
+
+    to execute only tests whose paths match `tests/rules` or `tests/maintenance`.
+
+  - Intended as an **optional, faster pre-flight** command that contributors run manually to iterate quickly on rule changes and core maintenance behavior.
+  - Does **not** replace `ci-verify:full` and is **not** used by hooks or CI; it exists purely for faster local feedback.
+
+Developers should rely on:
+
+- `npm run ci-verify:full` for a full CI-equivalent check (and what will run on push via Husky).
+- `npm run ci-verify` or `npm run ci-verify:fast` for quicker, targeted local feedback loops when working on rules or maintenance logic.
+
+## How Semantic Versioning Is Determined
+
+semantic-release uses Conventional Commits (see `docs/conventional-commits-guide.md`) to infer version changes:
+
+- `feat:` → **minor** version bump.
+- `fix:` → **patch** version bump.
+- `feat!` or `fix!` (or any type with `!`) or a `BREAKING CHANGE:` footer → **major** version bump.
+- Other types (`docs`, `style`, `refactor`, `test`, `chore`, `ci`, `build`, `perf`) → no release.
+
+Because releases are determined solely from commit history, it is important that all commits merged to `main` follow the documented Conventional Commits standard.
+
+## Supported Runtime and Tooling
+
+The pipeline runs against the following Node.js versions:
+
+- Node `18.x`
+- Node `20.x`
+
+The package itself declares:
+
+- `engines.node: ">=18.18.0"`
+- `peerDependencies.eslint: "^9.0.0"`
+
+User-facing docs are aligned with these constraints:
+
+- README “Prerequisites” section.
+- `user-docs/api-reference.md` "Supported runtime" line.
+
+## When Things Go Wrong
+
+- If **quality checks fail** (build, tests, lint, type-check, duplication, format, or audits), the workflow fails before any release attempt.
+- If semantic-release encounters a non-token, non-OTP error, the job fails and no release is published.
+- If `NPM_TOKEN` is missing or invalid, or if npm requires an OTP, the workflow succeeds but skips publishing; this is treated as a configuration issue rather than a code failure.
+- If the post-deployment smoke test fails, the job fails even though a package may have been published; this indicates an urgent regression in the published artifact.
+
+In all of these cases, the failing run is visible in the `CI/CD Pipeline` workflow on GitHub, and maintainers should fix the underlying issue before merging further changes to `main`.

package/docs/cli-integration.md

@@ -0,0 +1,22 @@
+# CLI Integration Guide
+
+Story: docs/stories/001.0-DEV-PLUGIN-SETUP.story.md  
+Requirement: REQ-PLUGIN-STRUCTURE - Validate plugin registers via CLI
+
+Integration tests for the ESLint CLI plugin are included in the Jest test suite under `tests/integration/cli-integration.test.ts`.
+
+## Running CLI Integration Tests
+
+To run only the CLI integration tests:
+
+```bash
+npm test -- tests/integration/cli-integration.test.ts
+```
+
+To run the full test suite:
+
+```bash
+npm test
+```
+
+These tests invoke the ESLint CLI with the plugin configured, verifying that rule errors are reported (or not) as expected when code is passed via `stdin`. Ensure your ESLint flat config (`eslint.config.js`) loads the plugin before running these tests.

package/docs/code-quality-refactor-opportunities-2025-12-03.md

@@ -0,0 +1,78 @@
+# Code Quality and Security Refactor Opportunities (2025-12-03)
+
+Created autonomously by voder.ai
+
+This note captures small, low-risk refactors that can be implemented incrementally to further improve maintainability and security without changing public behavior.
+
+## 1. Decompose maintenance CLI implementation
+
+**Files:**
+
+- `src/maintenance/cli.ts`
+
+**Motivation:**
+
+- `cli.ts` is one of the larger source files and currently owns argument parsing, flag normalization, subcommand dispatch, and user-facing messaging.
+- While it still passes `max-lines` and `max-lines-per-function` rules, splitting responsibilities would improve navigability.
+
+**Potential refactors:**
+
+- Extract a dedicated `src/maintenance/flags.ts` module responsible solely for:
+  - Defining the `CliFlags` shape and defaults.
+  - Implementing `applyFlag` / `parseFlags` behavior and validation.
+- Extract a `src/maintenance/commands.ts` module for the four subcommand handlers:
+  - `handleDetect`, `handleVerify`, `handleReport`, `handleUpdate`.
+  - Keep `runMaintenanceCli` as a small coordination layer that wires parsed arguments to these handlers.
+
+## 2. Narrow helper responsibilities in require-story helpers
+
+**Files:**
+
+- `src/rules/helpers/require-story-helpers.ts`
+- `src/rules/helpers/require-story-core.ts`
+
+**Motivation:**
+
+- These helpers concentrate multiple kinds of functionality: AST visitor construction, IO behavior, message construction, and small utility predicates.
+- Individual functions are reasonably sized, but the number of exported helpers makes the files dense.
+
+**Potential refactors:**
+
+- Introduce a dedicated `src/rules/helpers/require-story-io.ts` (already partially present) as the single place for reading and writing files in tests and rules.
+- Move purely structural helpers (e.g., small predicates, formatting helpers) into a `require-story-utils.ts`-style module so each file focuses on a single axis of responsibility.
+
+## 3. Revisit targeted ESLint suppressions
+
+**Files:**
+
+- `src/rules/helpers/valid-story-reference-helpers.ts` (single `no-unused-vars` suppression on a type-only parameter)
+- `src/rules/helpers/valid-annotation-options.ts` (single `max-params` suppression for a central option-normalization helper)
+- `tests/utils/ts-language-options.ts` (single `no-magic-numbers` suppression to allow ECMA version constants)
+
+**Motivation:**
+
+- Each suppression is currently justified and localized, but a small refactor could remove them entirely, simplifying the lint configuration.
+
+**Potential refactors:**
+
+- Replace the suppressed `max-params` helper with an options object parameter so callers pass a single argument while preserving type safety.
+- For the `no-unused-vars` case, explore using a `type`-only import or restructuring the function signature so all parameters are meaningfully consumed.
+- Extract ECMA version numbers into named constants in a small shared test utility module to avoid the need for a `no-magic-numbers` override.
+
+## 4. Optional: add slim wrappers for Story/Req detection utilities
+
+**Files:**
+
+- `src/utils/reqAnnotationDetection.ts`
+- `src/utils/annotation-checker.ts`
+
+**Motivation:**
+
+- These utilities are well-tested but contain a moderate amount of conditional logic for different AST node types.
+
+**Potential refactors:**
+
+- Introduce thin, strongly-typed wrapper functions for the most common call sites (e.g., “analyze function declaration for traceability annotations”) that hide some of the configuration detail from rule implementations.
+- This would make rule modules slightly smaller and more declarative, leaving the complex branching in a shared, well-tested location.
+
+These refactors should be tackled incrementally, one small change at a time, with existing Jest tests and ESLint rules acting as safety nets to ensure behavior remains unchanged.

package/docs/config-presets.md

@@ -0,0 +1,38 @@
+# Configuration Presets
+
+This document describes the built-in configuration presets provided by the `eslint-plugin-traceability` plugin.
+
+## Recommended Preset
+
+Use the **recommended** preset to enable the core traceability rule set with default settings.
+
+```javascript
+// eslint.config.js
+import js from "@eslint/js";
+import traceability from "eslint-plugin-traceability";
+
+export default [js.configs.recommended, traceability.configs.recommended];
+```
+
+This preset enables the following rules with severities tuned for common usage (most at `error`, with `traceability/valid-annotation-format` at `warn` to reduce noise):
+
+- `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`
+
+## Strict Preset
+
+Use the **strict** preset to enforce the same core rules, with potential future enhancements for stricter policies. Like the recommended preset, it configures `traceability/valid-annotation-format` as a `warn` to avoid excessive noise from format-only issues.
+
+```javascript
+// eslint.config.js
+import js from "@eslint/js";
+import traceability from "eslint-plugin-traceability";
+
+export default [js.configs.recommended, traceability.configs.strict];
+```
+
+The **strict** preset currently mirrors the **recommended** rules, but may include additional constraints in future plugin versions.