eslint-plugin-traceability 1.17.0 → 1.18.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-# [1.17.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.16.1...v1.17.0) (2025-12-09)
+# [1.18.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.17.1...v1.18.0) (2025-12-18)
 
 
 ### Features
 
-* allow configuring additional excluded test helper callbacks ([d266197](https://github.com/voder-ai/eslint-plugin-traceability/commit/d26619721b1826fe97d01a63647f07505e35c846))
+* add annotationPlacement option for branch annotations ([9cf4189](https://github.com/voder-ai/eslint-plugin-traceability/commit/9cf41897cdbc962eb41f304847ba8a911987d0fd))
 
 # Changelog
 

package/README.md

@@ -1,6 +1,10 @@
 # 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.
+An ESLint plugin that creates searchable verification indices in your code, enabling systematic validation of requirement-to-code mapping.
+
+**The Core Value:** Transforms an impossible question ("Does code exist somewhere that should support requirement X?") into a tractable question ("Does this annotated code actually support the requirement it claims to?").
+
+The plugin requires `@supports` annotations at key verification points (functions and control flow branches), creating direct checkpoints where each annotation is a verifiable claim you can search, find, and verify locally without needing to understand the broader codebase context.
 
 ## Attribution
 
@@ -89,21 +93,89 @@ export default [
 
 The plugin exposes several rules. For **new configurations**, the unified function-level rule and `@supports` annotations are the canonical choice; the `@story` and `@req` forms remain available primarily for backward compatibility and gradual migration.
 
-- `traceability/require-traceability` – **Unified function-level traceability rule.** Ensures that in-scope functions and methods have both story coverage and requirement coverage. It accepts either `@supports` (preferred for new code) or legacy `@story` / `@req` annotations and is enabled by default in the plugin's `recommended` and `strict` presets.
-- `traceability/require-story-annotation` – Legacy function-level rule key that focuses on the **story** side of function-level traceability. It is kept for backward compatibility and is wired to the same underlying engine as `traceability/require-traceability`, so existing configurations that refer to this rule continue to work. New configurations should normally rely on `traceability/require-traceability` instead of enabling this rule directly.
-- `traceability/require-req-annotation` – Legacy function-level rule key that focuses on the **requirement** side of function-level traceability. Like `traceability/require-story-annotation`, it is retained for backward compatibility and conceptually composes the same checks exposed by `traceability/require-traceability`. New configurations can usually rely on the unified rule alone unless you have specific reasons to tune the legacy keys separately.
-- `traceability/require-branch-annotation` – Enforces presence of branch annotations on significant control-flow branches (if/else, switch cases, loops, try/catch). Branch annotations can use a single `@supports` line (preferred) or the older `@story`/`@req` pair for backward compatibility. (See the rule documentation in the plugin's user guide.)
-- `traceability/valid-annotation-format` – Enforces correct format of traceability annotations, including `@supports` (preferred), `@story`, and `@req`. (See the rule documentation in the plugin's user guide.)
-- `traceability/valid-story-reference` – Validates that story references (whether written via `@story` or embedded in `@supports`) point to existing story files. (See the rule documentation in the plugin's user guide.)
-- `traceability/valid-req-reference` – Validates that requirement identifiers (whether written via `@req` or embedded in `@supports`) point to existing requirement IDs in your story files. (See the rule documentation in the plugin's user guide.)
-- `traceability/require-test-traceability` – Enforces traceability conventions in test files by requiring file-level `@supports` annotations, story references in `describe` blocks, and `[REQ-...]` prefixes in `it`/`test` names. (See the rule documentation in the plugin's user guide.)
-- `traceability/no-redundant-annotation` – Detects and optionally removes redundant traceability annotations on simple leaf statements that are already covered by an enclosing annotated scope. It is enabled at severity `warn` in both the `recommended` and `strict` presets by default; consumers can override its severity (including promoting it to `error`) or disable it explicitly in their ESLint configuration if they prefer.
-- `traceability/prefer-supports-annotation` – Optional migration helper that recommends converting legacy single-story `@story`/`@req` JSDoc blocks and inline comments into the newer `@supports` format. It is disabled by default and must be explicitly enabled. The legacy rule name `traceability/prefer-implements-annotation` remains available as a deprecated alias. (See the rule documentation in the plugin's user guide.)
+#### Core Verification Index Rules
+
+- `traceability/require-traceability` – **Unified function-level verification rule.** Ensures every function has a verification checkpoint. Without this, functions could exist without explaining their purpose, breaking verification completeness. Accepts either `@supports` (preferred for new code) or legacy `@story` / `@req` annotations and is enabled by default in the plugin's `recommended` and `strict` presets.
+
+- `traceability/require-story-annotation` – Legacy function-level rule key that focuses on the **story** side of function-level verification. It is kept for backward compatibility and is wired to the same underlying engine as `traceability/require-traceability`. New configurations should normally rely on `traceability/require-traceability` instead.
+
+- `traceability/require-req-annotation` – Legacy function-level rule key that focuses on the **requirement** side of function-level verification. Like `traceability/require-story-annotation`, it is retained for backward compatibility. New configurations can usually rely on the unified rule alone unless you have specific reasons to tune the legacy keys separately.
+
+- `traceability/require-branch-annotation` – **Creates verification checkpoints at every branch** (if/else/switch/try/catch). This enables local verification - you can check each branch independently without understanding the entire function. Without branch annotations, you must read entire functions to find branch logic. With branch annotations, you can verify each branch by searching for the requirement ID. Branch annotations can use `@supports` (preferred) or the older `@story`/`@req` pair for backward compatibility.
+
+- `traceability/valid-annotation-format` – **Ensures annotations are searchable** with consistent patterns. Verification workflows depend on being able to search for requirement IDs reliably. Enforces correct format of traceability annotations, including `@supports` (preferred), `@story`, and `@req`.
+
+- `traceability/valid-story-reference` – **Validates story file references** to ensure verification checkpoints point to real documentation. Validates that story references (whether written via `@story` or embedded in `@supports`) point to existing story files.
+
+- `traceability/valid-req-reference` – **Validates requirement identifiers** to ensure verification checkpoints reference valid requirements. Validates that requirement identifiers (whether written via `@req` or embedded in `@supports`) point to existing requirement IDs in your story files.
+
+- `traceability/require-test-traceability` – **Enforces verification conventions in test files** by requiring file-level `@supports` annotations, story references in `describe` blocks, and `[REQ-...]` prefixes in `it`/`test` names. This ensures tests are traceable back to requirements for comprehensive verification coverage.
+
+#### Quality Rules
+
+- `traceability/no-redundant-annotation` – **Removes annotations on simple statements** already covered by enclosing scope. These don't create useful verification checkpoints (no branches to verify), so removing them reduces noise without hurting verifiability. It is enabled at severity `warn` in both the `recommended` and `strict` presets by default; consumers can override its severity or disable it explicitly.
+
+- `traceability/prefer-supports-annotation` – **Optional migration helper** that recommends converting legacy single-story `@story`/`@req` JSDoc blocks and inline comments into the newer `@supports` format for better verification trails. It is disabled by default and must be explicitly enabled. The legacy rule name `traceability/prefer-implements-annotation` remains available as a deprecated alias.
 
 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 the contribution guide in the repository.
 
+## How It Works
+
+### The Verification Workflow
+
+Traceability annotations enable systematic requirement verification through a simple three-step process:
+
+1. **Search:** `grep -r "REQ-AUTH-VALIDATION" src/`
+2. **Find:** Get a list of every location claiming to support that requirement
+3. **Verify:** For each result, read the annotation and adjacent code to confirm they match
+
+### Why Annotations at Every Branch
+
+Each annotation creates a **local verification checkpoint**:
+
+- ✅ **Searchable** - Direct search finds all implementation claims
+- ✅ **Local** - Annotation is adjacent to the code being verified
+- ✅ **No context needed** - Verify the claim without understanding control flow
+- ✅ **Parallelizable** - Multiple reviewers work independently
+- ✅ **Complete coverage** - No code can exist without explaining its purpose
+
+This enables you to verify requirements systematically rather than trying to remember which code should implement what.
+
+### Example: Verifying a Switch Statement
+
+```javascript
+switch (severity) {
+  // @supports docs/stories/logging.md REQ-SEVERITY-LEVELS
+  case "low":
+    logLevel = "info";
+    break;
+  // @supports docs/stories/logging.md REQ-SEVERITY-LEVELS
+  case "moderate":
+    logLevel = "warn";
+    break;
+  // @supports docs/stories/logging.md REQ-SEVERITY-LEVELS
+  case "high":
+    logLevel = "error";
+    break;
+}
+```
+
+**Verification process:**
+
+- Search finds 3 annotations
+- Verify each: "Does this case handle REQ-SEVERITY-LEVELS correctly?"
+- Time: ~30 seconds per case, ~90 seconds total
+- Can be split across team members
+
+**Without explicit annotations:**
+
+- Must read entire switch to understand what it does
+- Must remember which requirement you're checking
+- Cannot split the work effectively
+- Risk missing cases or misunderstanding intent
+
 ## Quick Start
 
 1. Create a flat ESLint config file (`eslint.config.js`):
@@ -143,6 +215,30 @@ function initAuth() {
 npx eslint "src/**/*.js"
 ```
 
+## Common Misconceptions
+
+### "The annotations are redundant"
+
+**Reality:** The apparent redundancy is intentional indexing. Each annotation is a separate verification checkpoint. When the same requirement appears in multiple branches, each annotation creates an independent checkpoint that can be verified in ~30 seconds without understanding the broader code structure.
+
+Removing "duplicate" annotations would break the verification workflow by forcing reviewers to trace through code structure instead of verifying local claims.
+
+### "This only works for small codebases"
+
+**Reality:** The plugin is specifically designed for codebases where manual review is impractical. Small codebases could use manual review; larger ones need systematic, searchable verification indices to make requirement validation tractable.
+
+### "This is just documentation"
+
+**Reality:** These are verification indices, not documentation. The goal is searchability and local verification, not explaining code. Documentation aims to reduce redundancy; verification indices intentionally create checkpoints for independent validation.
+
+### "Inheritance would reduce boilerplate"
+
+**Reality:** Inheritance would break verification tractability. When you search for a requirement, you need to find every place that implements it - not find a parent annotation and manually trace what inherits from it. Direct, explicit annotations at each implementation point enable grep-based verification.
+
+## Verification Workflow Guide
+
+For detailed verification workflows, examples, and best practices, see the [Verification Workflow Guide](docs/verification-workflow-guide.md).
+
 ## API Reference
 
 Detailed API specification and configuration options can be found in the [API Reference](user-docs/api-reference.md).

package/lib/src/index.js

@@ -86,61 +86,77 @@ RULE_NAMES.forEach(
  *   and diagnostics).
  *
  * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED REQ-CONFIGURABLE-SCOPE REQ-EXPORT-PRIORITY
+ * @supports docs/stories/010.4-DEV-UNIFIED-FUNCTION-RULE-AND-ALIASES.story.md REQ-UNIFIED-ALIAS-ENGINE
  */
-{
+function createAliasRuleMeta(unifiedRule, legacyRule) {
+    if (!legacyRule) {
+        return null;
+    }
+    const baseMeta = (unifiedRule.meta ?? {});
+    const legacyMeta = (legacyRule.meta ?? {});
+    return {
+        ...baseMeta,
+        ...legacyMeta,
+        docs: {
+            ...(baseMeta.docs ?? {}),
+            ...(legacyMeta.docs ?? {}),
+        },
+        messages: {
+            ...(baseMeta.messages ?? {}),
+            ...(legacyMeta.messages ?? {}),
+        },
+        schema: legacyMeta.schema ??
+            baseMeta.schema ??
+            [],
+        hasSuggestions: legacyMeta.hasSuggestions ??
+            baseMeta.hasSuggestions,
+        fixable: legacyMeta.fixable ??
+            baseMeta.fixable,
+        deprecated: legacyMeta.deprecated ??
+            baseMeta.deprecated,
+        replacedBy: legacyMeta.replacedBy ??
+            baseMeta.replacedBy,
+        type: legacyMeta.type ??
+            baseMeta.type ??
+            "problem",
+    };
+}
+/**
+ * Wire up the unified `require-traceability` rule and its legacy alias rules
+ * so that they share the same implementation while preserving legacy metadata.
+ *
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED REQ-EXPORT-PRIORITY
+ * @supports docs/stories/010.4-DEV-UNIFIED-FUNCTION-RULE-AND-ALIASES.story.md REQ-UNIFIED-ALIAS-ENGINE
+ */
+function wireUnifiedFunctionAnnotationAliases() {
     const unifiedRule = rules["require-traceability"];
     const legacyStoryRule = rules["require-story-annotation"];
     const legacyReqRule = rules["require-req-annotation"];
     if (unifiedRule) {
         const createAliasRule = (legacyRule) => {
-            if (!legacyRule) {
+            const mergedMeta = createAliasRuleMeta(unifiedRule, legacyRule);
+            if (!mergedMeta) {
                 return unifiedRule;
             }
-            const baseMeta = (unifiedRule.meta ?? {});
-            const legacyMeta = (legacyRule.meta ?? {});
-            const mergedMeta = {
-                ...baseMeta,
-                ...legacyMeta,
-                docs: {
-                    ...(baseMeta.docs ?? {}),
-                    ...(legacyMeta.docs ?? {}),
-                },
-                messages: {
-                    ...(baseMeta.messages ?? {}),
-                    ...(legacyMeta.messages ?? {}),
-                },
-                schema: legacyMeta.schema ??
-                    baseMeta.schema ??
-                    [],
-                hasSuggestions: legacyMeta.hasSuggestions ??
-                    baseMeta.hasSuggestions,
-                fixable: legacyMeta.fixable ??
-                    baseMeta.fixable,
-                deprecated: legacyMeta.deprecated ??
-                    baseMeta.deprecated,
-                replacedBy: legacyMeta.replacedBy ??
-                    baseMeta.replacedBy,
-                type: legacyMeta.type ??
-                    baseMeta.type ??
-                    "problem",
-            };
-            const aliasRule = {
+            return {
                 ...unifiedRule,
                 meta: mergedMeta,
                 create: unifiedRule.create,
             };
-            return aliasRule;
         };
         rules["require-story-annotation"] = createAliasRule(legacyStoryRule);
         rules["require-req-annotation"] = createAliasRule(legacyReqRule);
     }
 }
+wireUnifiedFunctionAnnotationAliases();
 /**
  * @supports docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md REQ-RULE-NAME
  * Wire up traceability/prefer-supports-annotation as the primary rule name and
  * traceability/prefer-implements-annotation as its deprecated alias.
+ *
+ * @supports docs/stories/010.4-DEV-UNIFIED-FUNCTION-RULE-AND-ALIASES.story.md REQ-MIGRATION-RULE-NAMING
  */
-{
+function wirePreferSupportsAlias() {
     const implementsRule = rules["prefer-implements-annotation"];
     if (implementsRule) {
         const originalMeta = implementsRule.meta ?? {};
@@ -163,6 +179,7 @@ RULE_NAMES.forEach(
         }
     }
 }
+wirePreferSupportsAlias();
 /**
  * Plugin metadata used by ESLint for debugging and caching.
  *
@@ -226,6 +243,9 @@ const TRACEABILITY_RULE_SEVERITIES = {
  * @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
+ *
+ * @supports docs/stories/007.0-DEV-ERROR-REPORTING.story.md REQ-ERROR-SEVERITY
+ * @supports docs/stories/002.0-DEV-ESLINT-CONFIG.story.md REQ-CONFIG-PRESETS
  */
 function createTraceabilityFlatConfig() {
     return {

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

@@ -7,6 +7,7 @@ export declare const EXIT_USAGE = 2;
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-DETECT - CLI surface for detection of stale annotations
  * @req REQ-MAINT-SAFE - Return specific exit codes for stale vs clean states
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-SAFE
  */
 export declare function handleDetect(normalized: NormalizedCliArgs): number;
 /**
@@ -14,6 +15,7 @@ export declare function handleDetect(normalized: NormalizedCliArgs): number;
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-VERIFY - CLI surface for verification of annotations
  * @req REQ-MAINT-SAFE - Return distinct exit codes for verification failures
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-VERIFY REQ-MAINT-SAFE
  */
 export declare function handleVerify(normalized: NormalizedCliArgs): number;
 /**
@@ -21,6 +23,7 @@ export declare function handleVerify(normalized: NormalizedCliArgs): number;
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-REPORT - CLI surface for human-readable maintenance reports
  * @req REQ-MAINT-SAFE - Support machine-readable formats for safe automation
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-REPORT REQ-MAINT-SAFE
  */
 export declare function handleReport(normalized: NormalizedCliArgs): number;
 /**
@@ -28,5 +31,6 @@ export declare function handleReport(normalized: NormalizedCliArgs): number;
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UPDATE - CLI surface for updating annotation references
  * @req REQ-MAINT-SAFE - Provide dry-run mode and explicit parameter checks
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE REQ-MAINT-SAFE
  */
 export declare function handleUpdate(normalized: NormalizedCliArgs): number;

package/lib/src/maintenance/commands.js

@@ -28,6 +28,7 @@ exports.EXIT_USAGE = 2;
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-DETECT - CLI surface for detection of stale annotations
  * @req REQ-MAINT-SAFE - Return specific exit codes for stale vs clean states
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-SAFE
  */
 function handleDetect(normalized) {
     const flags = (0, flags_1.parseFlags)(normalized);
@@ -54,6 +55,7 @@ Run 'traceability-maint report' for a structured summary.`);
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-VERIFY - CLI surface for verification of annotations
  * @req REQ-MAINT-SAFE - Return distinct exit codes for verification failures
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-VERIFY REQ-MAINT-SAFE
  */
 function handleVerify(normalized) {
     const flags = (0, flags_1.parseFlags)(normalized);
@@ -71,6 +73,7 @@ function handleVerify(normalized) {
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-REPORT - CLI surface for human-readable maintenance reports
  * @req REQ-MAINT-SAFE - Support machine-readable formats for safe automation
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-REPORT REQ-MAINT-SAFE
  */
 function handleReport(normalized) {
     const flags = (0, flags_1.parseFlags)(normalized);
@@ -96,6 +99,7 @@ function handleReport(normalized) {
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UPDATE - CLI surface for updating annotation references
  * @req REQ-MAINT-SAFE - Provide dry-run mode and explicit parameter checks
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE REQ-MAINT-SAFE
  */
 function handleUpdate(normalized) {
     const flags = (0, flags_1.parseFlags)(normalized);

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

@@ -7,6 +7,7 @@
  * @req REQ-MAINT-VERIFY
  * @req REQ-MAINT-REPORT
  * @req REQ-MAINT-SAFE
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-UPDATE REQ-MAINT-BATCH REQ-MAINT-VERIFY REQ-MAINT-REPORT REQ-MAINT-SAFE
  */
 export { detectStaleAnnotations } from "./detect";
 export { updateAnnotationReferences } from "./update";

package/lib/src/maintenance/index.js

@@ -10,6 +10,7 @@ exports.generateMaintenanceReport = exports.verifyAnnotations = exports.batchUpd
  * @req REQ-MAINT-VERIFY
  * @req REQ-MAINT-REPORT
  * @req REQ-MAINT-SAFE
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-UPDATE REQ-MAINT-BATCH REQ-MAINT-VERIFY REQ-MAINT-REPORT REQ-MAINT-SAFE
  */
 var detect_1 = require("./detect");
 Object.defineProperty(exports, "detectStaleAnnotations", { enumerable: true, get: function () { return detect_1.detectStaleAnnotations; } });

package/lib/src/maintenance/report.js

@@ -12,8 +12,8 @@ const detect_1 = require("./detect");
  */
 function generateMaintenanceReport(codebasePath) {
     const staleAnnotations = (0, detect_1.detectStaleAnnotations)(codebasePath);
-    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md // @req REQ-MAINT-SAFE - When no stale annotations are found, return empty string to indicate no actions required
-    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md // @req REQ-MAINT-REPORT - When stale annotations exist, produce a newline-separated report
+    // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - When no stale annotations are found, return empty string to indicate no actions required
+    // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-REPORT - When stale annotations exist, produce a newline-separated report
     if (staleAnnotations.length === 0) {
         return "";
     }

package/lib/src/maintenance/update.js

@@ -40,6 +40,7 @@ const utils_1 = require("./utils");
  * Helper to process a single file for annotation reference updates
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UPDATE
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE
  */
 function processFileForAnnotationUpdates(fullPath, regex, newPath, replacementCountRef) {
     const content = fs.readFileSync(fullPath, "utf8"); // getAllFiles already returns regular files
@@ -78,8 +79,7 @@ function updateAnnotationReferences(codebasePath, oldPath, newPath) {
      * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
      * @req REQ-MAINT-UPDATE
      */
-    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-    // @req REQ-MAINT-UPDATE
+    // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE
     if (!fs.existsSync(codebasePath) ||
         !fs.statSync(codebasePath).isDirectory()) {
         return 0;
@@ -92,11 +92,13 @@ function updateAnnotationReferences(codebasePath, oldPath, newPath) {
      * Iterate over all files and replace annotation references
      * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
      * @req REQ-MAINT-UPDATE
+     * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE
      */
     /**
      * Loop over each discovered file path
      * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
      * @req REQ-MAINT-UPDATE
+     * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE
      */
     for (const fullPath of files) {
         processFileForAnnotationUpdates(fullPath, regex, newPath, replacementCountRef);

package/lib/src/rules/helpers/test-callback-exclusion.d.ts

@@ -8,6 +8,7 @@
  * @story docs/stories/013-exclude-test-framework-callbacks.proposed.md
  * @req REQ-TEST-CALLBACK-EXCLUSION - Provide reusable test callback exclusion logic
  */
+import type { TSESTree } from "@typescript-eslint/utils";
 /**
  * Options controlling how test callbacks are treated by the helpers.
  *
@@ -21,6 +22,9 @@ interface CallbackExclusionOptions {
     excludeTestCallbacks?: boolean;
     additionalTestHelperNames?: string[];
 }
+type TraceabilityNodeWithParent = TSESTree.Node & {
+    parent?: TraceabilityNodeWithParent | null;
+};
 /**
  * Determine whether a node represents a callback passed to a known test
  * framework function (Jest, Mocha, Vitest, etc).
@@ -34,6 +38,6 @@ interface CallbackExclusionOptions {
  *
  * @req REQ-TEST-CALLBACK-EXCLUSION
  */
-declare function isTestFrameworkCallback(node: any, options?: CallbackExclusionOptions): boolean;
+declare function isTestFrameworkCallback(node: TraceabilityNodeWithParent | null | undefined, options?: CallbackExclusionOptions): boolean;
 export type { CallbackExclusionOptions };
 export { isTestFrameworkCallback };

package/lib/src/rules/helpers/test-callback-exclusion.js

@@ -1,14 +1,4 @@
 "use strict";
-/**
- * Shared helpers for determining whether a function-like node should be
- * treated as a test framework callback that may be excluded from
- * function-level annotation requirements.
- *
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
- * @story docs/stories/013-exclude-test-framework-callbacks.proposed.md
- * @req REQ-TEST-CALLBACK-EXCLUSION - Provide reusable test callback exclusion logic
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isTestFrameworkCallback = isTestFrameworkCallback;
 /**
@@ -91,7 +81,8 @@ function isTestFrameworkCallback(node, options) {
     if (!parent || parent.type !== "CallExpression") {
         return false;
     }
-    const callee = parent.callee;
+    const callExpressionParent = parent;
+    const callee = callExpressionParent.callee;
     if (callee.type === "Identifier") {
         return isRecognizedTestHelperName(callee.name, options);
     }

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

@@ -175,8 +175,8 @@ function validateStoryAnnotation(context, comment, rawValue, options) {
         return;
     }
     // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-    // @req REQ-PATH-FORMAT - Reject @story values containing internal whitespace as invalid
-    if (/\s/.test(trimmed)) {
+    // @req REQ-PATH-FORMAT - Reject @story values containing internal whitespace that do not collapse into a valid story path
+    if (/\s/.test(trimmed) && !pathPattern.test(collapsed)) {
         reportInvalidStoryFormat(context, comment, collapsed, options);
         return;
     }
@@ -223,6 +223,12 @@ function validateReqAnnotation(context, comment, rawValue, options) {
         return;
     }
     const collapsed = (0, valid_annotation_utils_1.collapseAnnotationValue)(trimmed);
+    // Allow mixed @req/@supports lines to pass without additional @req validation,
+    // while still validating simple multi-line @req identifiers that collapse
+    // to a single token.
+    if (collapsed.includes("@supports")) {
+        return;
+    }
     const reqPattern = options.reqPattern;
     // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
     // @req REQ-REQ-FORMAT - Flag @req identifiers that do not match the configured pattern

package/lib/src/rules/no-redundant-annotation.js

@@ -326,6 +326,10 @@ const rule = {
                 if (process.env.TRACEABILITY_DEBUG === "1") {
                     console.log("[no-redundant-annotation] BlockStatement parent=%s statements=%d", parent && parent.type, Array.isArray(node.body) ? node.body.length : 0);
                 }
+                // @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-CATCH-BLOCK-HANDLING
+                if (parent && parent.type === "CatchClause") {
+                    return;
+                }
                 const scopePairs = collectScopePairs(context, parent, options.maxScopeDepth);
                 debugScopePairs(parent, scopePairs);
                 if (scopePairs.size === 0)

package/lib/src/rules/prefer-implements-annotation.js

@@ -286,17 +286,8 @@ function tryBuildInlineAutoFix(context, comments, storyIndex, reqIndices) {
  * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
  * @req REQ-MIGRATE-INLINE
  */
-function handleInlineStorySequence(context, group, startIndex) {
+function collectReqIndicesAfterStory(group, startIndex) {
     const n = group.length;
-    const current = group[startIndex];
-    const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(current.value || "");
-    if (!normalized || !/^@story\b/.test(normalized)) {
-        return startIndex + 1;
-    }
-    if (/^@supports\b/.test(normalized)) {
-        return startIndex + 1;
-    }
-    const storyIndex = startIndex;
     const reqIndices = [];
     let j = startIndex + 1;
     while (j < n) {
@@ -312,6 +303,19 @@ function handleInlineStorySequence(context, group, startIndex) {
         }
         break;
     }
+    return { reqIndices, nextIndex: j };
+}
+function handleInlineStorySequence(context, group, startIndex) {
+    const current = group[startIndex];
+    const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(current.value || "");
+    if (!normalized || !/^@story\b/.test(normalized)) {
+        return startIndex + 1;
+    }
+    if (/^@supports\b/.test(normalized)) {
+        return startIndex + 1;
+    }
+    const storyIndex = startIndex;
+    const { reqIndices, nextIndex } = collectReqIndicesAfterStory(group, startIndex);
     if (reqIndices.length === 0) {
         context.report({
             node: current,
@@ -333,7 +337,7 @@ function handleInlineStorySequence(context, group, startIndex) {
             messageId: "preferImplements",
         });
     }
-    return reqIndices[reqIndices.length - 1] + 1;
+    return nextIndex;
 }
 /**
  * Process a contiguous group of inline line comments, identifying legacy
@@ -343,19 +347,20 @@ function handleInlineStorySequence(context, group, startIndex) {
  * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
  * @req REQ-MIGRATE-INLINE
  */
+function advanceInlineGroupIndex(context, group, currentIndex) {
+    const current = group[currentIndex];
+    const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(current.value || "");
+    if (!normalized || !/^@story\b/.test(normalized)) {
+        return currentIndex + 1;
+    }
+    return handleInlineStorySequence(context, group, currentIndex);
+}
 function processInlineGroup(context, group) {
     if (group.length === 0)
         return;
-    const n = group.length;
     let i = 0;
-    while (i < n) {
-        const current = group[i];
-        const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(current.value || "");
-        if (!normalized || !/^@story\b/.test(normalized)) {
-            i += 1;
-            continue;
-        }
-        i = handleInlineStorySequence(context, group, i);
+    while (i < group.length) {
+        i = advanceInlineGroupIndex(context, group, i);
     }
 }
 /**

package/lib/src/rules/require-branch-annotation.js

@@ -99,6 +99,12 @@ const rule = {
                         items: { type: "string" },
                         uniqueItems: true,
                     },
+                    /**
+                     * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG REQ-DEFAULT-BACKWARD-COMPAT
+                     */
+                    annotationPlacement: {
+                        enum: ["before", "inside"],
+                    },
                 },
                 additionalProperties: false,
             },
@@ -124,6 +130,16 @@ const rule = {
             return branchTypesOrListener;
         }
         const branchTypes = branchTypesOrListener;
+        /**
+         * Resolve annotation placement configuration with backward-compatible default.
+         *
+         * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG REQ-DEFAULT-BACKWARD-COMPAT
+         */
+        const rawOptions = context.options[0] || {};
+        const _annotationPlacement = rawOptions.annotationPlacement === "inside" ||
+            rawOptions.annotationPlacement === "before"
+            ? rawOptions.annotationPlacement
+            : "before";
         const storyFixCountRef = { count: 0 };
         const handlers = {};
         branchTypes.forEach((type) => {