eslint-plugin-traceability 1.0.0

package/.voder/traceability/docs-stories-002.0-DEV-ESLINT-CONFIG.story.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<traceability>
+  <specification>docs/stories/002.0-DEV-ESLINT-CONFIG.story.md</specification>
+  <status>PASSED</status>
+  <last_validated>2025-11-16T17:05:16.869Z</last_validated>
+  <last_modified>2025-11-16T00:07:54.396Z</last_modified>
+  <evidence>- src/index.ts exports `configs.recommended` and `configs.strict` with the required rule presets (REQ-CONFIG-PRESETS)
+- eslint.config.js is written in ESLint v9 flat‐config format and includes sections for JS, TS, common CJS files, and ignores (REQ-FLAT-CONFIG)
+- valid-story-reference rule schema supports `storyDirectories`, `allowAbsolutePaths`, and `requireStoryExtension` options (REQ-CUSTOMIZABLE-PATHS, REQ-RULE-OPTIONS)
+- CI build and linting pass without errors, demonstrating seamless integration (EXECUTION reports 92%, CODE_QUALITY reports lint/test/type-check OK)
+- docs/config-presets.md and docs/eslint-9-setup-guide.md provide clear setup instructions, examples, and troubleshooting (Documentation acceptance)</evidence>
+  <notes>All acceptance criteria for story 002.0-DEV-ESLINT-CONFIG have been met: the plugin provides both recommended and strict presets, follows ESLint v9 flat config best practices, allows rule customization, integrates with JS/TS projects, and includes comprehensive documentation and configuration validation.</notes>
+</traceability>

package/.voder/traceability/docs-stories-003.0-DEV-FUNCTION-ANNOTATIONS.story.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<traceability>
+  <specification>docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md</specification>
+  <status>FAILED</status>
+  <last_validated>2025-11-16T17:03:12.326Z</last_validated>
+  <last_modified>2025-11-16T00:07:54.405Z</last_modified>
+  <evidence>Inspection of src/rules/require-story-annotation.ts and src/rules/require-req-annotation.ts shows only FunctionDeclaration nodes are handled (no arrow functions, function expressions, or class methods), there is no support for TypeScript‐specific syntax or parser configuration in RuleTester (only default parser used), and neither rule exposes configuration to scope which functions are checked or to prioritize exported functions. Key requirements REQ-FUNCTION-DETECTION (expressions/arrow functions), REQ-CONFIGURABLE-SCOPE, REQ-EXPORT-PRIORITY, and REQ-TYPESCRIPT-SUPPORT are not implemented.</evidence>
+  <notes>While basic function‐level detection and error reporting exist for missing @story and @req, the implementation does not satisfy the full breadth of acceptance criteria and technical requirements outlined in the story. Additional work is needed to support all function patterns, configurability, and TypeScript integration.</notes>
+</traceability>

package/.voder/traceability/docs-stories-004.0-DEV-BRANCH-ANNOTATIONS.story.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<traceability>
+  <specification>docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md</specification>
+  <status>FAILED</status>
+  <last_validated>2025-11-16T17:03:22.383Z</last_validated>
+  <last_modified>2025-11-16T00:07:54.419Z</last_modified>
+  <evidence>In src/rules/require-branch-annotation.ts the rule.meta.schema is an empty array (schema: []), and the documentation (docs/rules/require-branch-annotation.md) explicitly states “This rule does not accept any options.” However, the story’s Requirements include REQ-CONFIGURABLE-SCOPE: “Allow configuration of which branch types require annotations.” There is no code to accept or handle any configuration options for branch scopes, nor any tests for that behavior.</evidence>
+  <notes>While the core detection, parsing, and error reporting for branch annotations are implemented and well-tested, the required ability to configure which branch types are enforced is missing. The story is therefore not fully satisfied.</notes>
+</traceability>

package/.voder/traceability/docs-stories-005.0-DEV-ANNOTATION-VALIDATION.story.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<traceability>
+  <specification>docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md</specification>
+  <status>PASSED</status>
+  <last_validated>2025-11-16T17:03:32.682Z</last_validated>
+  <last_modified>2025-11-16T00:07:54.431Z</last_modified>
+  <evidence>The `valid-annotation-format` rule is present in src/rules/valid-annotation-format.ts with appropriate meta, messages, and schema. Tests in tests/rules/valid-annotation-format.test.ts cover valid and invalid @story and @req formats, including block comments and single-line comments, and all tests pass (100% statements, 100% lines, 92.85% branches). Documentation exists at docs/rules/valid-annotation-format.md with examples matching implementation. The rule is exported in src/index.ts and included in both 'recommended' and 'strict' configs. ESLint linting, Jest testing, type checking, and coverage checks all pass.</evidence>
+  <notes>The annotation format validation rule fully meets the story’s acceptance criteria: it validates @story and @req syntax, follows ESLint best practices, integrates with other rules, provides clear error messages, handles edge cases (multiline/block comments), and is documented with examples. Tests ensure REQ-FORMAT-SPECIFICATION, REQ-SYNTAX-VALIDATION, REQ-PATH-FORMAT, REQ-REQ-FORMAT, REQ-MULTILINE-SUPPORT, REQ-FLEXIBLE-PARSING, and REQ-ERROR-SPECIFICITY are satisfied.</notes>
+</traceability>

package/.voder/traceability/docs-stories-006.0-DEV-FILE-VALIDATION.story.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<traceability>
+  <specification>docs/stories/006.0-DEV-FILE-VALIDATION.story.md</specification>
+  <status>PASSED</status>
+  <last_validated>2025-11-16T17:03:17.855Z</last_validated>
+  <last_modified>2025-11-16T00:07:54.445Z</last_modified>
+  <evidence>Found src/rules/valid-story-reference.ts with full implementation of REQ-FILE-EXISTENCE, REQ-PATH-RESOLUTION, REQ-SECURITY-VALIDATION, REQ-PERFORMANCE-OPTIMIZATION (caching), REQ-PROJECT-BOUNDARY, and REQ-CONFIGURABLE-PATHS, all annotated with @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md. Corresponding tests in tests/rules/valid-story-reference.test.ts cover valid and invalid scenarios (file exists, extension check, path traversal, absolute paths) and reference the story and requirement IDs. package.json scripts include Jest run, and CI reports 100% passing tests and high coverage.</evidence>
+  <notes>The valid-story-reference rule meets all acceptance criteria: core functionality, ESLint best practices, integration with format validation, clear error messages, and documented examples. Tests confirm correct behavior across file system scenarios.</notes>
+</traceability>

package/.voder/traceability/docs-stories-007.0-DEV-ERROR-REPORTING.story.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<traceability>
+  <specification>docs/stories/007.0-DEV-ERROR-REPORTING.story.md</specification>
+  <status>FAILED</status>
+  <last_validated>2025-11-16T17:04:41.461Z</last_validated>
+  <last_modified>2025-11-16T00:07:54.454Z</last_modified>
+  <evidence>A review of the rule implementations shows that none of the context.report() calls supply “suggest” fixes or instruction text: for example, require-story-annotation only reports messageId “missingStory” with text “Missing @story annotation” and no suggestion on how to add one. None of the rules use ESLint’s suggest API or include actionable guidance (e.g. “Add @story docs/stories/...”) or dynamic context beyond basic identifiers. The docs/rules markdown do not document full error messages or suggestions, and existing unit and CLI tests only assert that errors fire, not that they carry specific, actionable message text or locations beyond the default. </evidence>
+  <notes>The 007.0-DEV-ERROR-REPORTING story calls for clear, actionable error messages including suggested fixes, context and consistent formatting. While basic error reporting exists, there is no implementation of suggestion API, no contextual guidance, and no documentation of full message format. Therefore the story is not satisfied.</notes>
+</traceability>

package/.voder/traceability/docs-stories-008.0-DEV-AUTO-FIX.story.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<traceability>
+  <specification>docs/stories/008.0-DEV-AUTO-FIX.story.md</specification>
+  <status>FAILED</status>
+  <last_validated>2025-11-16T17:04:59.379Z</last_validated>
+  <last_modified>2025-11-16T00:07:54.465Z</last_modified>
+  <evidence>Assessment error: 400 This model's maximum context length is 200000 tokens. However, your messages resulted in 206091 tokens (204696 in the messages, 1395 in the functions). Please reduce the length of the messages or functions.</evidence>
+  <notes>Technical error during assessment</notes>
+</traceability>

package/.voder/traceability/docs-stories-009.0-DEV-MAINTENANCE-TOOLS.story.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<traceability>
+  <specification>docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md</specification>
+  <status>PASSED</status>
+  <last_validated>2025-11-16T17:05:08.140Z</last_validated>
+  <last_modified>2025-11-16T00:07:54.476Z</last_modified>
+  <evidence>- src/maintenance/detect.ts, update.ts, batch.ts, report.ts, utils.ts implement all six REQ-MAINT-* requirements with JSDoc @story and @req annotations.  
+- tests/maintenance/detect.test.ts & detect-isolated.test.ts cover REQ-MAINT-DETECT (detectStaleAnnotations).  
+- tests/maintenance/update.test.ts & update-isolated.test.ts cover REQ-MAINT-UPDATE (updateAnnotationReferences).  
+- tests/maintenance/batch.test.ts cover REQ-MAINT-BATCH and REQ-MAINT-VERIFY (batchUpdateAnnotations, verifyAnnotations).  
+- tests/maintenance/report.test.ts covers REQ-MAINT-REPORT (generateMaintenanceReport) and implicitly REQ-MAINT-SAFE.  
+- npm test (Jest) runs all tests with 100% passing, maintaining >96% coverage in maintenance code.  
+- Code preserves formatting, handles missing directories, nested structures, permission errors, and writes updates safely.  
+</evidence>
+  <notes>All acceptance criteria for story 009.0-DEV-MAINTENANCE-TOOLS are satisfied: core functionality, quality standards, integration, UX feedback, error handling, and documentation via JSDoc and test coverage. Maintenance tools are fully implemented and validated by tests.</notes>
+</traceability>

package/.voder/traceability/docs-stories-010.0-DEV-DEEP-VALIDATION.story.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<traceability>
+  <specification>docs/stories/010.0-DEV-DEEP-VALIDATION.story.md</specification>
+  <status>PASSED</status>
+  <last_validated>2025-11-16T17:03:50.351Z</last_validated>
+  <last_modified>2025-11-16T00:07:54.487Z</last_modified>
+  <evidence>- src/rules/valid-req-reference.ts implements deep validation logic with AST comment parsing, path resolution, caching, regex-based requirement extraction, and reports both invalidPath and reqMissing messages.
+- Tests in tests/rules/valid-req-reference.test.ts cover valid references (including bullet-list fixture), missing requirements, path traversal, and absolute paths, all passing under Jest: exit code 0, coverage report included.
+- Documentation in docs/rules/valid-req-reference.md and docs/stories/010.0-DEV-DEEP-VALIDATION.story.md align, and the plugin builds, lints, type-checks, and tests successfully (npm test shows 96%+ statements, 84%+ branches overall).</evidence>
+  <notes>The implementation provides the required core functionality for deep requirement content validation: it parses story files, matches @req IDs, handles path errors, caches content, reports clear errors, and is fully tested. All acceptance criteria are satisfied.</notes>
+</traceability>

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [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.
+
+### Fixed
+
+- N/A

package/CONTRIBUTING.md

@@ -0,0 +1,97 @@
+# Contributing to eslint-plugin-traceability
+
+Thank you for your interest in contributing to `eslint-plugin-traceability`! We welcome bug reports, feature requests, and pull requests. To ensure a smooth process, please follow the guidelines below.
+
+## Reporting Issues
+
+If you encounter a bug or have a feature request:
+
+1. Search existing issues to see if the problem or suggestion has already been reported.
+2. If not, open a new issue on GitHub: [Issue Tracker](https://github.com/voder-ai/eslint-plugin-traceability/issues).
+3. Provide a clear and descriptive title, steps to reproduce, expected behavior, and any relevant screenshots or logs.
+4. Specify your environment:
+   - `node` version: `node -v`
+   - `eslint` version: `npx eslint -v`
+   - Operating system and shell.
+
+## Pull Request Process
+
+When submitting a pull request (PR):
+
+1. Fork the repository and create a branch for your changes.
+2. Commit your changes in small, logical increments. Use descriptive commit messages.
+3. Ensure all tests pass and the project builds successfully.
+4. Push your branch to GitHub and open a PR against the `main` branch.
+5. Reference any related issues in your PR description.
+6. A maintainer will review your changes and may request updates or approve the PR.
+
+## Commit Message Conventions
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/) format. Commit messages should be structured as:
+
+```
+tag: short description
+
+optional body explaining why the change was made
+
+optional footer (e.g., BREAKING CHANGE: ...)
+```
+
+Common commit types:
+
+- `feat:` A new feature
+- `fix:` A bug fix
+- `docs:` Documentation only changes
+- `style:` Code style changes (formatting, linting)
+- `refactor:` Code changes that neither fix a bug nor add a feature
+- `perf:` Performance improvements
+- `test:` Adding or updating tests
+- `chore:` Other changes that do not modify src or test files
+
+## Coding Style and Quality Checks
+
+We enforce code style and quality using ESLint, Prettier, TypeScript, and other tools. Please run the following commands before submitting your PR:
+
+```bash
+# Build the project and generate types
+npm run build
+
+# Run TypeScript type checks
+npm run type-check
+
+# Lint code
+npm run lint
+
+# Run tests
+npm test
+
+# Check formatting (no changes)
+npm run format:check
+
+# Check duplication threshold
+npm run duplication
+```
+
+Ensure there are no errors or warnings in the output.
+
+## Developing Locally
+
+1. Clone your fork and install dependencies:
+
+   ```bash
+   git clone https://github.com/<your-username>/eslint-plugin-traceability.git
+   cd eslint-plugin-traceability
+   npm install
+   ```
+
+````
+
+2. Run the tests in watch mode:
+
+   ```bash
+npm test
+````
+
+3. Make your changes, and verify that tests and linting continue to pass.
+
+Thank you for helping improve `eslint-plugin-traceability`!

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 voder.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# eslint-plugin-traceability
+
+A customizable ESLint plugin that enforces traceability annotations in your code, ensuring each implementation is linked to its requirement or test case.
+
+## Attribution
+
+Created autonomously by [voder.ai](https://voder.ai).
+
+## Installation
+
+Prerequisites: Node.js v12+ and ESLint v9+.
+
+1. Using npm  
+   npm install --save-dev eslint-plugin-traceability
+2. Using Yarn  
+   yarn add --dev eslint-plugin-traceability
+
+For detailed setup with ESLint v9, see docs/eslint-9-setup-guide.md.
+
+## Usage
+
+Add the plugin to your ESLint configuration and enable the rules.
+
+Example eslint.config.js (ESLint v9 flat 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",
+    },
+  },
+];
+```
+
+### 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))
+
+For development and contribution guidelines, see docs/eslint-plugin-development-guide.md.
+
+## Quick Start
+
+1. Create a flat ESLint config file (`eslint.config.js`):
+
+```javascript
+// eslint.config.js
+import traceability from "eslint-plugin-traceability";
+
+export default [
+  // Load the traceability plugin's recommended rule set
+  traceability.configs.recommended,
+];
+```
+
+2. Annotate your functions or modules:
+
+```js
+/**
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ */
+function initAuth() {
+  // implementation...
+}
+```
+
+3. Run ESLint:
+
+```bash
+npx eslint "src/**/*.js"
+```
+
+## API Reference
+
+Detailed API specification and configuration options can be found in the [API Reference](user-docs/api-reference.md).
+
+## Examples
+
+Practical usage examples and sample configurations are available in the [Examples](user-docs/examples.md) document.
+
+## Plugin Validation
+
+You can validate the plugin by running ESLint CLI with the plugin on a sample file:
+
+```bash
+# Validate missing @story annotation (should report an error)
+npx eslint --no-eslintrc --config eslint.config.js sample.js --rule 'traceability/require-story-annotation:error'
+```
+
+This command runs ESLint with the plugin, pointing at `eslint.config.js` flat config.
+
+Replace `sample.js` with your JavaScript or TypeScript file.
+
+## Running Tests
+
+You can run tests and quality checks locally using the npm scripts provided:
+
+```bash
+# Run all tests with coverage
+npm test
+
+# Run linting with zero tolerance for warnings
+npm run lint -- --max-warnings=0
+
+# Check code formatting
+npm run format:check
+
+# Check duplication threshold
+npm run duplication
+```
+
+Coverage reports will be generated in the `coverage/` directory.
+
+## CLI Integration
+
+The `cli-integration.js` script runs end-to-end CLI integration tests for the plugin, verifying behavior when used via the ESLint CLI.
+
+Usage:
+
+```bash
+# Run the CLI integration tests
+node cli-integration.js
+```
+
+This script executes tests that:
+
+- Report an error when the `@story` annotation is missing.
+- Do not report an error when the `@story` annotation is present.
+
+The CLI integration tests are also executed automatically in CI under the `integration-tests` job.
+
+## Documentation Links
+
+- ESLint v9 Setup Guide: 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
+- 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

package/cli-integration.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/* eslint-env node */
+/**
+ * CLI integration tests for ESLint Traceability Plugin
+ * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
+ * @req REQ-PLUGIN-STRUCTURE - Validate plugin registers via CLI
+ */
+const { spawnSync } = require("child_process");
+const path = require("path");
+const configPath = path.resolve(__dirname, "eslint.config.js");
+
+/**
+ * Helper to execute ESLint CLI integration tests for the traceability plugin
+ * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
+ * @req REQ-PLUGIN-STRUCTURE - Utility for invoking ESLint with flat config in integration tests
+ */
+function runEslint(code, rule) {
+  const eslintPkgDir = path.dirname(require.resolve("eslint/package.json"));
+  const eslintCliPath = path.join(eslintPkgDir, "bin", "eslint.js");
+  const args = [
+    "--no-config-lookup",
+    "--config",
+    configPath,
+    "--stdin",
+    "--stdin-filename",
+    "foo.js",
+    "--rule",
+    "no-unused-vars:off",
+    "--rule",
+    "no-constant-condition:off",
+    "--rule",
+    "no-empty:off",
+    "--rule",
+    "traceability/require-story-annotation:off",
+    "--rule",
+    "traceability/require-req-annotation:off",
+    "--rule",
+    "traceability/require-branch-annotation:off",
+    "--rule",
+    "traceability/valid-annotation-format:off",
+    "--rule",
+    "traceability/valid-story-reference:off",
+    "--rule",
+    "traceability/valid-req-reference:off",
+    "--rule",
+    rule,
+  ];
+  return spawnSync(process.execPath, [eslintCliPath, ...args], {
+    encoding: "utf-8",
+    input: code,
+  });
+}
+
+const tests = [
+  {
+    name: "reports error when @story annotation is missing",
+    code: "function foo() {}",
+    rule: "traceability/require-story-annotation:error",
+    expectedStatus: 1,
+  },
+  {
+    name: "does not report error when @story annotation is present",
+    code: `
+/**
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ */
+function foo() {}
+`,
+    rule: "traceability/require-story-annotation:error",
+    expectedStatus: 0,
+  },
+  {
+    name: "reports error when requirement reference is missing",
+    code: `/**\n * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md\n * @req REQ-NON-EXISTENT\n */\nfunction foo() {}`,
+    rule: "traceability/valid-req-reference:error",
+    expectedStatus: 1,
+  },
+  {
+    name: "reports error when requirement reference uses path traversal",
+    code: `/**\n * @story ../docs/stories/001.0-DEV-PLUGIN-SETUP.story.md\n * @req REQ-PLUGIN-STRUCTURE\n */\nfunction foo() {}`,
+    rule: "traceability/valid-req-reference:error",
+    expectedStatus: 1,
+  },
+  {
+    name: "reports error when requirement reference uses absolute path",
+    code: `/**\n * @story /absolute/docs/stories/001.0-DEV-PLUGIN-SETUP.story.md\n * @req REQ-PLUGIN-STRUCTURE\n */\nfunction foo() {}`,
+    rule: "traceability/valid-req-reference:error",
+    expectedStatus: 1,
+  },
+  {
+    name: "reports error when @req annotation is missing",
+    code: `/**
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ */\nfunction foo() {}`,
+    rule: "traceability/require-req-annotation:error",
+    expectedStatus: 1,
+  },
+  {
+    name: "does not report error when @req annotation is present",
+    code: `/**
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ */\nfunction foo() {}`,
+    rule: "traceability/require-req-annotation:error",
+    expectedStatus: 0,
+  },
+  {
+    name: "reports error for missing branch annotations",
+    code: `if (true) {}`,
+    rule: "traceability/require-branch-annotation:error",
+    expectedStatus: 1,
+  },
+  {
+    name: "does not report error for branch with annotations",
+    code: `// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md\n// @req REQ-BRANCH-DETECTION\nif (true) {}`,
+    rule: "traceability/require-branch-annotation:error",
+    expectedStatus: 0,
+  },
+  {
+    name: "reports invalid annotation format",
+    code: `/**\n * @story invalid/path.txt\n * @req INVALID\n */\nfunction foo() {}`,
+    rule: "traceability/valid-annotation-format:error",
+    expectedStatus: 1,
+  },
+  {
+    name: "valid annotation format passes",
+    code: `/**\n * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md\n * @req REQ-FORMAT-SPECIFICATION\n */\nfunction foo() {}`,
+    rule: "traceability/valid-annotation-format:error",
+    expectedStatus: 0,
+  },
+  {
+    name: "reports missing story file reference",
+    code: `/**\n * @story docs/stories/nonexistent.story.md\n */\nfunction foo() {}`,
+    rule: "traceability/valid-story-reference:error",
+    expectedStatus: 1,
+  },
+  {
+    name: "existing story file reference passes",
+    code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction foo() {}`,
+    rule: "traceability/valid-story-reference:error",
+    expectedStatus: 0,
+  },
+];
+
+let exitCode = 0;
+tests.forEach(({ name, code, rule, expectedStatus }) => {
+  const result = runEslint(code, rule);
+  if (result.status !== expectedStatus) {
+    console.error(
+      `Test "${name}" failed. Expected status ${expectedStatus}, got ${result.status}.`,
+    );
+    console.error("stdout:", result.stdout);
+    exitCode = 1;
+  }
+});
+
+process.exit(exitCode);