eslint-plugin-traceability 1.0.1 → 1.0.2

package/.voder/plan.md

@@ -1,15 +1,12 @@
 ## NOW  
-Create `user-docs/api-reference.md` containing a skeleton outline of the plugin’s public API (listing each exported rule and config).
+Standardize all test file headers under `tests/` to use JSDoc block comments with proper `@story` and `@req` annotations, replacing any inline comments for traceability.
 
 ## NEXT  
-- Populate `user-docs/api-reference.md` with detailed descriptions, options, default values, and JSDoc‐style examples for every rule and config.  
-- Add `user-docs/examples.md` with runnable end-to-end ESLint configurations and CLI invocation scenarios.  
-- Update `README.md` to link to the new API reference and examples under `user-docs/`.  
-- Replace the separate `ci.yml` and `deploy.yml` workflows with a single `.github/workflows/ci-cd.yml` that on every push to `main` runs build, lint, type-check, test, audit, and then publishes to npm.  
-- Remove or disable the old `deploy.yml` and adjust any branch/tag filters so only `ci-cd.yml` handles publishing.
+- Refactor test bodies to adopt explicit GIVEN-WHEN-THEN (Arrange-Act-Assert) structure and eliminate any custom logic (e.g. sorting/flatMap) in expectations.  
+- Add a post-deployment smoke-test job to `.github/workflows/ci-cd.yml` that installs the freshly published package in a clean workspace and executes the `cli-integration.js` script.  
+- Incorporate `cli-integration.js` into the CI “quality-checks” job so the pipeline mirrors the Husky pre-push behavior.
 
 ## LATER  
-- In `ci-cd.yml`, add a smoke-test job that installs the freshly published package in a clean workspace and exercises basic CLI commands.  
-- Record the unified CI/CD and documentation decisions in ADRs (e.g. `docs/decisions/ADR-unified-cicd.md`, `docs/decisions/ADR-api-reference.md`).  
-- Migrate to semantic-release (or GitHub Releases) to automate version bumps and changelog updates.  
-- Introduce a scheduled dependency/vulnerability audit job in CI to catch new advisories early.
+- Write additional edge-case unit tests to cover any uncovered branches in the maintenance utilities.  
+- Monitor and optimize test execution times to keep unit tests fast (<100 ms each).  
+- Once testing and version-control improvements push both support areas above 90%, perform a full functionality reassessment.

package/.voder/progress-log-areas.csv

@@ -32,3 +32,4 @@ overall,functionality,code_quality,testing,execution,documentation,dependencies,
 77.5,,77,60,93,95,100,100,95
 76.875,,93,92,95,85,100,95,55
 89.6,,90,90,95,82,100,95,75
+91,,93,87,95,85,100,95,85

package/.voder/progress-log.csv

@@ -31,3 +31,4 @@
 77.5
 76.875
 89.6
+91

package/docs/decisions/004-automated-version-bumping-for-ci-cd.md

@@ -0,0 +1,165 @@
+---
+status: "proposed"
+date: 2025-11-17
+decision-makers: [Development Team]
+consulted:
+  [
+    npm Documentation,
+    GitHub Actions Best Practices,
+    Semantic Versioning Specification,
+  ]
+informed: [Project Stakeholders, CI/CD Pipeline Maintainers]
+---
+
+# Automated Version Bumping for CI/CD Publishing
+
+## Context and Problem Statement
+
+The current CI/CD pipeline attempts to publish the package to npm on every push to the main branch, but lacks any mechanism to automatically increment the package version. This causes publish failures when the same version number already exists on npm, as npm does not allow republishing the same version. The pipeline fails with errors like "You cannot publish over the previously published versions" or similar npm publish conflicts.
+
+Currently, version bumping requires manual intervention through direct package.json edits, which is error-prone, interrupts the automated delivery flow, and creates a disconnect between the continuous integration process and package publishing. This breaks the principle of continuous delivery and creates friction in the development workflow.
+
+## Decision Drivers
+
+- Need for reliable automated publishing without manual intervention
+- Prevention of npm publish failures due to version conflicts
+- Alignment with semantic versioning principles for clear change communication
+- Integration with existing CI/CD pipeline and GitHub workflow
+- Maintainability of version history and changelog automation
+- Support for different types of releases (patch, minor, major)
+- Traceability of version changes to specific commits or pull requests
+- Minimal friction for developers while maintaining version discipline
+
+## Considered Options
+
+- npm version command with automated execution in CI/CD
+- Semantic Release with automated version detection
+- Manual version bumping with CI/CD workflow triggers
+- Version bumping through GitHub Actions with npm version
+
+## Decision Outcome
+
+Chosen option: "npm version command with automated execution in CI/CD", because it provides direct integration with npm tooling, maintains simplicity in the CI/CD pipeline, allows for both automated and manual control when needed, and follows established npm ecosystem practices without requiring complex semantic analysis tooling.
+
+### Implementation Strategy
+
+The CI/CD pipeline will be modified to:
+
+1. **Pre-publish Version Check**: Before attempting to publish, check if the current package.json version already exists on npm
+2. **Automatic Patch Increment**: If the version exists, automatically increment the patch version using `npm version patch`
+3. **Commit and Tag**: Create a version commit and git tag as part of the pipeline
+4. **Publish with New Version**: Proceed with npm publish using the incremented version
+5. **Changelog Update**: Automatically update CHANGELOG.md with the new version entry
+
+### Consequences
+
+- Good, because prevents all npm publish failures due to version conflicts
+- Good, because maintains automated delivery without manual intervention
+- Good, because creates proper git tags and version history
+- Good, because uses standard npm tooling that developers understand
+- Good, because allows for emergency manual version bumps when needed
+- Good, because integrates cleanly with existing CI/CD infrastructure
+- Neutral, because requires CI/CD pipeline to have git write access
+- Neutral, because creates additional commits in the main branch for version bumps
+- Bad, because does not automatically determine semantic version type (major/minor/patch)
+- Bad, because may create noise in git history with automated version commits
+
+### Confirmation
+
+Implementation compliance will be confirmed through:
+
+- CI/CD pipeline successfully publishes without version conflicts
+- Git repository contains version tags matching published npm versions
+- CHANGELOG.md automatically updated with version entries
+- No manual intervention required for routine publishing
+- Version bumps traceable through git commit history
+- package.json version always synchronized with published npm version
+
+## Pros and Cons of the Options
+
+### npm version command with automated execution in CI/CD
+
+Standard npm tooling with CI/CD automation provides reliable version management with minimal complexity.
+
+- Good, because uses native npm version management tools
+- Good, because creates proper git tags and version commits automatically
+- Good, because simple to understand and maintain in CI/CD
+- Good, because allows manual override for major/minor version bumps
+- Good, because integrates with existing npm publish workflow
+- Good, because provides immediate resolution to publish failures
+- Good, because maintains compatibility with npm ecosystem tools
+- Neutral, because requires configuration of git credentials in CI/CD
+- Neutral, because creates automated commits that may clutter history
+- Bad, because defaults to patch-level increments only
+- Bad, because does not analyze commit messages for semantic versioning
+
+### Semantic Release with automated version detection
+
+Automated semantic versioning based on commit message analysis and release automation.
+
+- Good, because fully automated semantic version determination
+- Good, because analyzes commit messages for version type
+- Good, because comprehensive release note generation
+- Good, because follows semantic versioning specification strictly
+- Good, because popular in open source ecosystem
+- Neutral, because requires standardized commit message format
+- Bad, because adds significant complexity to CI/CD pipeline
+- Bad, because requires team discipline for commit message formatting
+- Bad, because may be overkill for the current project size
+- Bad, because introduces external dependency on semantic-release tool
+- Bad, because harder to override for exceptional cases
+
+### Manual version bumping with CI/CD workflow triggers
+
+Requiring manual version increments before publishing with workflow validation.
+
+- Good, because provides full developer control over versioning
+- Good, because ensures deliberate version decisions
+- Good, because no automated commits or git history noise
+- Good, because simple to understand and implement
+- Neutral, because requires developer discipline for version management
+- Bad, because breaks continuous delivery principle
+- Bad, because requires manual intervention for every release
+- Bad, because prone to human error and forgotten version bumps
+- Bad, because does not solve the original npm publish failure problem
+- Bad, because creates friction in development workflow
+
+### Version bumping through GitHub Actions with npm version
+
+GitHub Actions-specific tooling for automated version management within the existing platform.
+
+- Good, because native integration with GitHub workflow ecosystem
+- Good, because can leverage GitHub-specific features like releases
+- Good, because may provide better integration with pull request workflows
+- Good, because uses familiar GitHub Actions patterns
+- Neutral, because similar capabilities to npm version approach
+- Bad, because locks solution to GitHub Actions platform specifically
+- Bad, because may require additional GitHub Actions marketplace dependencies
+- Bad, because potentially less portable to other CI/CD systems
+- Bad, because npm version command is more universally understood
+
+## More Information
+
+This decision addresses the immediate CI/CD publish failures while establishing a foundation for reliable automated delivery. The implementation should be flexible enough to support future migration to semantic release if the project grows to require more sophisticated version management.
+
+Key implementation considerations:
+
+- Configure CI/CD pipeline with appropriate git credentials for version commits
+- Set up git user configuration for automated commits
+- Ensure version tags follow consistent naming convention (v1.0.0 format)
+- Update CHANGELOG.md generation to work with automated version increments
+- Consider branch protection rules that allow CI/CD version commits
+- Document manual override process for major/minor version bumps
+
+This decision should be re-evaluated if:
+
+- Project adopts semantic versioning discipline across the team
+- Commit message standardization becomes feasible
+- Publishing frequency increases significantly requiring more sophisticated automation
+- The simple patch increment approach becomes insufficient for change communication
+
+Related resources:
+
+- [npm version command documentation](https://docs.npmjs.com/cli/v9/commands/npm-version)
+- [GitHub Actions CI/CD Best Practices](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments)
+- [Semantic Versioning Specification](https://semver.org/)

package/lib/tests/basic.test.js

@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 /**
- * Tests for basic plugin structure
+ * Tests for: docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
  * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
  * @req REQ-PLUGIN-STRUCTURE - plugin exports rules and configs
  */

package/lib/tests/index.test.js

@@ -45,6 +45,7 @@ describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", ()
         expect(index_1.default.configs).toBe(index_1.configs);
     });
     it("[REQ-PLUGIN-STRUCTURE] rules object has correct rule names", () => {
+        // Arrange: expected rule names in insertion order
         const expected = [
             "require-story-annotation",
             "require-req-annotation",
@@ -53,7 +54,10 @@ describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", ()
             "valid-story-reference",
             "valid-req-reference",
         ];
-        expect(Object.keys(index_1.rules).sort()).toEqual(expected.sort());
+        // Act: get actual rule names from plugin
+        const actual = Object.keys(index_1.rules);
+        // Assert: actual matches expected
+        expect(actual).toEqual(expected);
     });
     it("[REQ-RULE-REGISTRY] configs.recommended contains correct rule configuration", () => {
         const recommendedRules = index_1.configs.recommended[0].rules;

package/lib/tests/integration/file-validation.test.js

@@ -15,11 +15,10 @@ const eslintBin = path_1.default.resolve(__dirname, "../../node_modules/.bin/esl
 const configPath = path_1.default.resolve(__dirname, "../../eslint.config.js");
 describe("File and Req Validation CLI Integration (Story 006.0-DEV-FILE-VALIDATION)", () => {
     function runLint(code, rules) {
-        const ruleArgs = [
-            "--rule",
-            "no-unused-vars:off",
-            ...rules.flatMap((r) => ["--rule", r]),
-        ];
+        const ruleArgs = ["--rule", "no-unused-vars:off"];
+        for (const r of rules) {
+            ruleArgs.push("--rule", r);
+        }
         return (0, child_process_1.spawnSync)("node", [
             eslintBin,
             "--no-config-lookup",
@@ -35,26 +34,38 @@ describe("File and Req Validation CLI Integration (Story 006.0-DEV-FILE-VALIDATI
         });
     }
     it("[REQ-FILE-EXISTENCE] reports missing story file via CLI", () => {
+        // Arrange
         const code = "// @story docs/stories/missing-file.story.md";
+        // Act
         const res = runLint(code, ["traceability/valid-story-reference:error"]);
+        // Assert
         expect(res.status).toBe(1);
         expect(res.stdout).toContain("Story file");
     });
     it("[REQ-EXTENSION] reports invalid extension via CLI", () => {
+        // Arrange
         const code = "// @story docs/stories/001.0-DEV-PLUGIN-SETUP.md";
+        // Act
         const res = runLint(code, ["traceability/valid-story-reference:error"]);
+        // Assert
         expect(res.status).toBe(1);
         expect(res.stdout).toContain("Invalid story file extension");
     });
     it("[REQ-DEEP-PARSE] reports missing requirement via CLI", () => {
+        // Arrange
         const code = "// @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md\n// @req REQ-UNKNOWN";
+        // Act
         const res = runLint(code, ["traceability/valid-req-reference:error"]);
+        // Assert
         expect(res.status).toBe(1);
         expect(res.stdout).toContain("Requirement 'REQ-UNKNOWN' not found");
     });
     it("[REQ-DEEP-MATCH] valid story and requirement via CLI", () => {
+        // Arrange
         const code = "// @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md\n// @req REQ-PLUGIN-STRUCTURE";
+        // Act
         const res = runLint(code, ["traceability/valid-req-reference:error"]);
+        // Assert
         expect(res.status).toBe(0);
     });
 });

package/lib/tests/integration/plugin-validation.test.js

@@ -11,67 +11,73 @@ Object.defineProperty(exports, "__esModule", { value: true });
 /* eslint-env node, jest */
 const child_process_1 = require("child_process");
 const path_1 = __importDefault(require("path"));
+// Ensure ESLint CLI uses built plugin
 const eslintBin = path_1.default.resolve(__dirname, "../../node_modules/.bin/eslint");
 const configPath = path_1.default.resolve(__dirname, "../../eslint.config.js");
-function runEslint(code, rule) {
-    const args = [
-        "--no-config-lookup",
-        "--config",
-        configPath,
-        "--stdin",
-        "--stdin-filename",
-        "foo.js",
-        "--rule",
-        "no-unused-vars:off",
-        "--rule",
-        rule,
-    ];
-    // Use Node to run the ESLint CLI script
-    return (0, child_process_1.spawnSync)("node", [eslintBin, ...args], {
-        encoding: "utf-8",
-        input: code,
-    });
-}
-const cliTests = [
-    {
-        name: "[REQ-PLUGIN-STRUCTURE] reports error when @story annotation is missing",
-        code: "function foo() {}",
-        rule: "traceability/require-story-annotation:error",
-        expectedStatus: 1,
-        stdoutRegex: /require-story-annotation/,
-    },
-    {
-        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: "Require Req Annotation CLI (Story 003.0-DEV-FUNCTION-ANNOTATIONS)",
-        code: "function foo() {}",
-        rule: "traceability/require-req-annotation:error",
-        expectedStatus: 1,
-        stdoutRegex: /require-req-annotation/,
-    },
-    {
-        name: "Require Branch Annotation CLI (Story 004.0-DEV-BRANCH-ANNOTATIONS)",
-        code: "if (condition) {}",
-        rule: "traceability/require-branch-annotation:error",
-        expectedStatus: 1,
-        stdoutRegex: /require-branch-annotation/,
-    },
-];
 describe("ESLint CLI Integration (Story 001.0-DEV-PLUGIN-SETUP)", () => {
-    test.each(cliTests)("$name", ({ code, rule, expectedStatus, stdoutRegex }) => {
+    /**
+     * Helper to run ESLint CLI with the traceability plugin and custom rule
+     * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
+     * @req REQ-PLUGIN-STRUCTURE - Invoke ESLint CLI for integration testing
+     */
+    function runEslint(code, rule) {
+        const args = [
+            "--no-config-lookup",
+            "--config",
+            configPath,
+            "--stdin",
+            "--stdin-filename",
+            "foo.js",
+            "--rule",
+            "no-unused-vars:off",
+            "--rule",
+            rule,
+        ];
+        return (0, child_process_1.spawnSync)("node", [eslintBin, ...args], {
+            encoding: "utf-8",
+            input: code,
+        });
+    }
+    it("[REQ-PLUGIN-STRUCTURE] reports error when @story annotation is missing", () => {
+        // Arrange
+        const code = "function foo() {}";
+        const rule = "traceability/require-story-annotation:error";
+        // Act
+        const result = runEslint(code, rule);
+        // Assert
+        expect(result.status).toBe(1);
+        expect(result.stdout).toMatch(/require-story-annotation/);
+    });
+    it("[REQ-PLUGIN-STRUCTURE] does not report error when @story annotation is present", () => {
+        // Arrange
+        const code = `/**
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ */
+function foo() {}`;
+        const rule = "traceability/require-story-annotation:error";
+        // Act
+        const result = runEslint(code, rule);
+        // Assert
+        expect(result.status).toBe(0);
+    });
+    it("[REQ-REQ-CLI] reports error when @req annotation is missing", () => {
+        // Arrange
+        const code = "function foo() {}";
+        const rule = "traceability/require-req-annotation:error";
+        // Act
+        const result = runEslint(code, rule);
+        // Assert
+        expect(result.status).toBe(1);
+        expect(result.stdout).toMatch(/require-req-annotation/);
+    });
+    it("[REQ-BRANCH-CLI] reports error when branch annotations missing", () => {
+        // Arrange
+        const code = "if (true) {}";
+        const rule = "traceability/require-branch-annotation:error";
+        // Act
         const result = runEslint(code, rule);
-        expect(result.status).toBe(expectedStatus);
-        if (stdoutRegex) {
-            expect(result.stdout).toMatch(stdoutRegex);
-        }
+        // Assert
+        expect(result.status).toBe(1);
+        expect(result.stdout).toMatch(/require-branch-annotation/);
     });
 });

package/lib/tests/maintenance/detect-isolated.test.js

@@ -48,6 +48,7 @@ describe("detectStaleAnnotations isolated (Story 009.0-DEV-MAINTENANCE-TOOLS)",
         expect(result).toEqual([]);
     });
     it("[REQ-MAINT-DETECT] detects stale annotations in nested directories", () => {
+        // Arrange
         const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "tmp-nested-"));
         const nestedDir = path.join(tmpDir, "nested");
         fs.mkdirSync(nestedDir);
@@ -65,8 +66,12 @@ describe("detectStaleAnnotations isolated (Story 009.0-DEV-MAINTENANCE-TOOLS)",
  */
 `;
         fs.writeFileSync(filePath2, content2, "utf8");
+        // Act
         const result = (0, detect_1.detectStaleAnnotations)(tmpDir);
-        expect(result.sort()).toEqual(["stale1.story.md", "stale2.story.md"].sort());
+        // Assert
+        expect(result).toHaveLength(2);
+        expect(result).toContain("stale1.story.md");
+        expect(result).toContain("stale2.story.md");
     });
     it("[REQ-MAINT-DETECT] throws error on permission denied", () => {
         const tmpDir2 = fs.mkdtempSync(path.join(os.tmpdir(), "tmp-perm-"));

package/lib/tests/rules/require-branch-annotation.test.js

@@ -3,9 +3,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-// Tests for: docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-// @req REQ-BRANCH-DETECTION - Verify require-branch-annotation rule enforces branch annotations
+/**
+ * Tests for: docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-BRANCH-DETECTION - Verify require-branch-annotation rule enforces branch annotations
+ */
 const eslint_1 = require("eslint");
 const require_branch_annotation_1 = __importDefault(require("../../src/rules/require-branch-annotation"));
 const ruleTester = new eslint_1.RuleTester({

package/lib/tests/rules/require-story-annotation.test.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 /**
  * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Verify require-story-annotation rule enforces @story annotation on functions
  */
 const eslint_1 = require("eslint");
 const require_story_annotation_1 = __importDefault(require("../../src/rules/require-story-annotation"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/tests/basic.test.ts

@@ -1,5 +1,5 @@
 /**
- * Tests for basic plugin structure
+ * Tests for: docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
  * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
  * @req REQ-PLUGIN-STRUCTURE - plugin exports rules and configs
  */

package/tests/index.test.ts

@@ -12,6 +12,7 @@ describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", ()
   });
 
   it("[REQ-PLUGIN-STRUCTURE] rules object has correct rule names", () => {
+    // Arrange: expected rule names in insertion order
     const expected = [
       "require-story-annotation",
       "require-req-annotation",
@@ -20,7 +21,10 @@ describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", ()
       "valid-story-reference",
       "valid-req-reference",
     ];
-    expect(Object.keys(rules).sort()).toEqual(expected.sort());
+    // Act: get actual rule names from plugin
+    const actual = Object.keys(rules);
+    // Assert: actual matches expected
+    expect(actual).toEqual(expected);
   });
 
   it("[REQ-RULE-REGISTRY] configs.recommended contains correct rule configuration", () => {

package/tests/integration/file-validation.test.ts

@@ -12,11 +12,10 @@ const configPath = path.resolve(__dirname, "../../eslint.config.js");
 
 describe("File and Req Validation CLI Integration (Story 006.0-DEV-FILE-VALIDATION)", () => {
   function runLint(code: string, rules: string[]) {
-    const ruleArgs = [
-      "--rule",
-      "no-unused-vars:off",
-      ...rules.flatMap((r) => ["--rule", r]),
-    ];
+    const ruleArgs = ["--rule", "no-unused-vars:off"];
+    for (const r of rules) {
+      ruleArgs.push("--rule", r);
+    }
     return spawnSync(
       "node",
       [
@@ -37,31 +36,43 @@ describe("File and Req Validation CLI Integration (Story 006.0-DEV-FILE-VALIDATI
   }
 
   it("[REQ-FILE-EXISTENCE] reports missing story file via CLI", () => {
+    // Arrange
     const code = "// @story docs/stories/missing-file.story.md";
+    // Act
     const res = runLint(code, ["traceability/valid-story-reference:error"]);
+    // Assert
     expect(res.status).toBe(1);
     expect(res.stdout).toContain("Story file");
   });
 
   it("[REQ-EXTENSION] reports invalid extension via CLI", () => {
+    // Arrange
     const code = "// @story docs/stories/001.0-DEV-PLUGIN-SETUP.md";
+    // Act
     const res = runLint(code, ["traceability/valid-story-reference:error"]);
+    // Assert
     expect(res.status).toBe(1);
     expect(res.stdout).toContain("Invalid story file extension");
   });
 
   it("[REQ-DEEP-PARSE] reports missing requirement via CLI", () => {
+    // Arrange
     const code =
       "// @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md\n// @req REQ-UNKNOWN";
+    // Act
     const res = runLint(code, ["traceability/valid-req-reference:error"]);
+    // Assert
     expect(res.status).toBe(1);
     expect(res.stdout).toContain("Requirement 'REQ-UNKNOWN' not found");
   });
 
   it("[REQ-DEEP-MATCH] valid story and requirement via CLI", () => {
+    // Arrange
     const code =
       "// @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md\n// @req REQ-PLUGIN-STRUCTURE";
+    // Act
     const res = runLint(code, ["traceability/valid-req-reference:error"]);
+    // Assert
     expect(res.status).toBe(0);
   });
 });