eslint-plugin-traceability 1.17.1 → 1.19.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [1.17.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.17.0...v1.17.1) (2025-12-10)
+# [1.19.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.18.0...v1.19.0) (2025-12-18)
 
 
-### Bug Fixes
+### Features
 
-* avoid redundant-annotation false positives for catch blocks ([2ac69e2](https://github.com/voder-ai/eslint-plugin-traceability/commit/2ac69e2a03b54cf29bf2bc175771bf3b23aba6e9))
+* enforce inside-brace placement mode for branch annotations ([5c2129a](https://github.com/voder-ai/eslint-plugin-traceability/commit/5c2129a7c25717dc4ce14bf55bc4541ae07e5539))
 
 # 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/rules/no-redundant-annotation.js

@@ -86,7 +86,14 @@ function getScopePairs(context, scopeNode, parent) {
     const sourceCode = context.getSourceCode();
     // Branch-style scope: use the branch helpers to collect comment text.
     if (branch_annotation_helpers_1.DEFAULT_BRANCH_TYPES.includes(scopeNode.type)) {
-        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, scopeNode, parent);
+        /**
+         * Inside-brace annotations used as branch-level indicators (inside placement
+         * mode) should not be folded into scopePairs for redundancy purposes; only
+         * before-brace annotations define the covering scope here.
+         *
+         * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-NON-REDUNDANT-INSIDE REQ-PLACEMENT-CONFIG
+         */
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, scopeNode, parent, "before");
         return (0, annotation_scope_analyzer_1.extractStoryReqPairsFromText)(text);
     }
     const comments = getScopeCommentsFromJSDocAndLeading(sourceCode, scopeNode);

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) => {

package/lib/src/utils/branch-annotation-helpers.d.ts

@@ -10,6 +10,12 @@ export declare const DEFAULT_BRANCH_TYPES: readonly ["IfStatement", "SwitchCase"
  * Type for branch nodes supported by require-branch-annotation rule.
  */
 export type BranchType = (typeof DEFAULT_BRANCH_TYPES)[number];
+/**
+ * Placement options for branch annotations relative to their associated branch.
+ * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+ * @req REQ-PLACEMENT-CONFIG - Allow configuration of annotation placement (before/inside)
+ */
+export type AnnotationPlacement = "before" | "inside";
 /**
  * Validate branchTypes configuration option and return branch types to enforce,
  * or return an ESLint listener if configuration is invalid.
@@ -33,8 +39,9 @@ export declare function scanCommentLinesInRange(lines: string[], startIndex: num
  * @req REQ-COMMENT-ASSOCIATION - Associate inline comments with their corresponding code branches
  * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
  * @supports REQ-DUAL-POSITION-DETECTION
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
  */
-export declare function gatherBranchCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any, parent?: any): string;
+export declare function gatherBranchCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any, parent?: any, annotationPlacement?: AnnotationPlacement): string;
 /**
  * Report missing @story annotation tag on a branch node when that branch lacks a corresponding @story reference in its comments.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md

package/lib/src/utils/branch-annotation-helpers.js

@@ -195,6 +195,55 @@ function gatherCatchClauseCommentText(sourceCode, node, beforeText) {
     }
     return beforeText;
 }
+/**
+ * Gather annotation text for simple IfStatement branches, honoring the configured placement.
+ * When placement is "before", this helper preserves the existing behavior by returning the
+ * leading comment text unchanged. When placement is "inside", it switches to inside-brace
+ * semantics and scans for comments at the top of the consequent block.
+ * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+ * @supports REQ-INSIDE-BRACE-PLACEMENT
+ * @supports REQ-PLACEMENT-CONFIG
+ * @supports REQ-DEFAULT-BACKWARD-COMPAT
+ */
+function gatherSimpleIfCommentText(sourceCode, node, annotationPlacement, beforeText) {
+    if (annotationPlacement === "before") {
+        return beforeText;
+    }
+    if (annotationPlacement !== "inside") {
+        return beforeText;
+    }
+    if (!node.consequent || node.consequent.type !== "BlockStatement") {
+        return "";
+    }
+    const consequent = node.consequent;
+    const getCommentsInside = sourceCode.getCommentsInside;
+    if (typeof getCommentsInside === "function") {
+        try {
+            const insideComments = getCommentsInside(consequent) || [];
+            const insideText = insideComments.map(extractCommentValue).join(" ");
+            if (insideText) {
+                return insideText;
+            }
+        }
+        catch {
+            // fall through to line-based fallback
+        }
+    }
+    if (consequent.loc &&
+        consequent.loc.start &&
+        consequent.loc.end &&
+        typeof consequent.loc.start.line === "number" &&
+        typeof consequent.loc.end.line === "number") {
+        const lines = sourceCode.lines;
+        const startIndex = consequent.loc.start.line - 1;
+        const endIndex = consequent.loc.end.line - 1;
+        const insideText = scanCommentLinesInRange(lines, startIndex + 1, endIndex);
+        if (insideText) {
+            return insideText;
+        }
+    }
+    return "";
+}
 /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 function scanElseIfPrecedingComments(sourceCode, node) {
     const lines = sourceCode.lines;
@@ -316,8 +365,9 @@ function gatherSwitchCaseCommentText(sourceCode, node) {
  * @req REQ-COMMENT-ASSOCIATION - Associate inline comments with their corresponding code branches
  * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
  * @supports REQ-DUAL-POSITION-DETECTION
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
  */
-function gatherBranchCommentText(sourceCode, node, parent) {
+function gatherBranchCommentText(sourceCode, node, parent, annotationPlacement = "before") {
     /**
      * Conditional branch for SwitchCase nodes that may include inline comments.
      * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
@@ -332,13 +382,21 @@ function gatherBranchCommentText(sourceCode, node, parent) {
         return gatherCatchClauseCommentText(sourceCode, node, beforeText);
     }
     /**
-     * Conditional branch for IfStatement else-if nodes that may include inline comments
-     * after the else-if condition but before the consequent body.
+     * Conditional branch for IfStatement nodes, distinguishing between else-if branches
+     * (which preserve dual-position behavior) and simple if-branches that can honor
+     * the configured annotation placement (before or inside braces).
      * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
+     * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
      * @supports REQ-DUAL-POSITION-DETECTION
+     * @supports REQ-INSIDE-BRACE-PLACEMENT
+     * @supports REQ-PLACEMENT-CONFIG
+     * @supports REQ-DEFAULT-BACKWARD-COMPAT
      */
     if (node.type === "IfStatement") {
-        return gatherElseIfCommentText(sourceCode, node, parent, beforeText);
+        if (isElseIfBranch(node, parent)) {
+            return gatherElseIfCommentText(sourceCode, node, parent, beforeText);
+        }
+        return gatherSimpleIfCommentText(sourceCode, node, annotationPlacement, beforeText);
     }
     /**
      * Conditional branch for loop nodes that may include annotations either on the loop

package/lib/src/utils/branch-annotation-report-helpers.d.ts

@@ -5,6 +5,7 @@ import type { Rule } from "eslint";
  * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
  * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
  * @supports REQ-DUAL-POSITION-DETECTION
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
  */
 export declare function reportMissingAnnotations(context: Rule.RuleContext, node: any, storyFixCountRef: {
     count: number;

package/lib/src/utils/branch-annotation-report-helpers.js

@@ -22,8 +22,11 @@ function getIndentAndInsertPosForLine(sourceCode, line, fallbackIndent) {
     });
     return { indent, insertPos };
 }
-/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
-function getBaseBranchIndentAndInsertPos(sourceCode, node) {
+/**
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
+ */
+function getBaseBranchIndentAndInsertPos(sourceCode, node, _annotationPlacement) {
     let { indent, insertPos } = getIndentAndInsertPosForLine(sourceCode, node.loc.start.line, "");
     if (node.type === "CatchClause" && node.body) {
         const bodyNode = node.body;
@@ -50,32 +53,87 @@ function getBaseBranchIndentAndInsertPos(sourceCode, node) {
     return { indent, insertPos };
 }
 /**
- * Compute annotation-related metadata for a branch node.
- * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
- * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
- * @supports REQ-DUAL-POSITION-DETECTION
- * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-SUPPORTS-ALTERNATIVE
+ * Determine whether a node represents an else-if branch that should be used for
+ * determining comment insertion position.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  */
-function getBranchAnnotationInfo(sourceCode, node, parent) {
-    const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node, parent);
-    const hasSupports = /@supports\b/.test(text);
-    const missingStory = !/@story\b/.test(text) && !hasSupports;
-    const missingReq = !/@req\b/.test(text) && !hasSupports;
-    let { indent, insertPos } = getBaseBranchIndentAndInsertPos(sourceCode, node);
-    if (node.type === "IfStatement" &&
+function isElseIfBranchForInsert(node, parent) {
+    return (node &&
+        node.type === "IfStatement" &&
         parent &&
         parent.type === "IfStatement" &&
-        parent.alternate === node &&
-        node.consequent &&
+        parent.alternate === node);
+}
+/**
+ * Compute indentation and insert position for IfStatement branches, handling
+ * both simple if and else-if cases, respecting the configured annotation
+ * placement and indentation rules.
+ * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG REQ-INDENTATION-CORRECT
+ */
+function getIfStatementIndentAndInsertPos(sourceCode, node, options, context) {
+    const { parent, annotationPlacement } = options;
+    let { indent, insertPos } = context;
+    const hasBlockConsequent = node.consequent &&
         node.consequent.type === "BlockStatement" &&
         node.consequent.loc &&
-        node.consequent.loc.start) {
+        node.consequent.loc.start;
+    if (!hasBlockConsequent) {
+        return context;
+    }
+    const isElseIf = isElseIfBranchForInsert(node, parent);
+    const isSimpleIfInsidePlacement = annotationPlacement === "inside" && !isElseIf;
+    if (isSimpleIfInsidePlacement || isElseIf) {
         const commentLine = node.consequent.loc.start.line + 1;
         const commentLineInfo = getIndentAndInsertPosForLine(sourceCode, commentLine, indent);
         indent = commentLineInfo.indent;
         insertPos = commentLineInfo.insertPos;
+        context.indent = indent;
+        context.insertPos = insertPos;
     }
+    return context;
+}
+/**
+ * Compute which annotations are missing for a branch based on its gathered comment text.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
+ */
+function getBranchMissingFlags(sourceCode, node, parent, annotationPlacement) {
+    const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node, parent, annotationPlacement);
+    const hasSupports = /@supports\b/.test(text);
+    const missingStory = !/@story\b/.test(text) && !hasSupports;
+    const missingReq = !/@req\b/.test(text) && !hasSupports;
+    return { missingStory, missingReq };
+}
+/**
+ * Compute indentation and insert position used for auto-fix insertion on a branch.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
+ */
+function getBranchIndentAndInsertPos(sourceCode, node, parent, annotationPlacement) {
+    const { indent, insertPos } = getBaseBranchIndentAndInsertPos(sourceCode, node, annotationPlacement);
+    if (node.type === "IfStatement") {
+        const context = { indent, insertPos };
+        const updatedContext = getIfStatementIndentAndInsertPos(sourceCode, node, { parent, annotationPlacement }, context);
+        return {
+            indent: updatedContext.indent,
+            insertPos: updatedContext.insertPos,
+        };
+    }
+    return { indent, insertPos };
+}
+/**
+ * Compute annotation-related metadata for a branch node.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
+ * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
+ * @supports REQ-DUAL-POSITION-DETECTION
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-SUPPORTS-ALTERNATIVE
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
+ */
+function getBranchAnnotationInfo(sourceCode, node, parent, annotationPlacement) {
+    const { missingStory, missingReq } = getBranchMissingFlags(sourceCode, node, parent, annotationPlacement);
+    const { indent, insertPos } = getBranchIndentAndInsertPos(sourceCode, node, parent, annotationPlacement);
     return { missingStory, missingReq, indent, insertPos };
 }
 /**
@@ -84,11 +142,18 @@ function getBranchAnnotationInfo(sourceCode, node, parent) {
  * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
  * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
  * @supports REQ-DUAL-POSITION-DETECTION
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
  */
 function reportMissingAnnotations(context, node, storyFixCountRef) {
     const sourceCode = context.getSourceCode();
+    const rawOptions = context.options && context.options[0];
+    const annotationPlacement = rawOptions &&
+        (rawOptions.annotationPlacement === "inside" ||
+            rawOptions.annotationPlacement === "before")
+        ? rawOptions.annotationPlacement
+        : "before";
     const parent = node.parent;
-    const { missingStory, missingReq, indent, insertPos } = getBranchAnnotationInfo(sourceCode, node, parent);
+    const { missingStory, missingReq, indent, insertPos } = getBranchAnnotationInfo(sourceCode, node, parent, annotationPlacement);
     const actions = [
         {
             missing: missingStory,

package/lib/tests/rules/no-redundant-annotation.test.js

@@ -42,6 +42,10 @@ describe("no-redundant-annotation rule (Story 027.0-DEV-REDUNDANT-ANNOTATION-DET
                 name: "[REQ-CATCH-BLOCK-HANDLING] preserves catch block annotation from issue #6 scenario",
                 code: `async function example() {\n  try {\n    // @story prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.story.md\n    // @supports prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.md REQ-SAFE-ONLY\n    if (isSafeVersion({ version, vulnerabilityData })) {\n      return version;\n    }\n\n    // @story prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.story.md\n    // @supports prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.md REQ-SAFE-ONLY\n    if (!vulnerabilityData.isVulnerable) {\n      return version;\n    }\n  } catch (error) {\n    // @story prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.story.md\n    // @supports prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.md REQ-SAFE-ONLY\n    return null;\n  }\n}`,
             },
+            {
+                name: "[REQ-CATCH-BLOCK-HANDLING] preserves annotations in nested catch blocks with repeated requirements",
+                code: `async function nestedCatches() {\n  try {\n    await checkPrimary();\n  } catch (outerError) {\n    // @supports prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.md REQ-SAFE-ONLY\n    try {\n      await attemptRecovery(outerError);\n    } catch (innerError) {\n      // @supports prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.md REQ-SAFE-ONLY\n      await reportFailure(innerError);\n    }\n  }\n}`,
+            },
         ],
         invalid: [
             {
@@ -92,6 +96,12 @@ describe("no-redundant-annotation rule (Story 027.0-DEV-REDUNDANT-ANNOTATION-DET
                 output: `/**\n * @story docs/stories/009.0-EXAMPLE.story.md\n * @supports REQ-SUP-A, REQ-SUP-B\n */\nfunction example() {\n  const supported = checkSupport();\n}`,
                 errors: [{ messageId: "redundantAnnotation" }],
             },
+            {
+                name: "[REQ-SCOPE-ANALYSIS][REQ-STATEMENT-SIGNIFICANCE] flags redundant annotation in finally block that repeats try-path coverage",
+                code: `async function example() {\n  // @supports docs/stories/010.0-EXAMPLE.story.md REQ-SAFE-OPERATION\n  try {\n    await doWork();\n  } finally {\n    // @supports docs/stories/010.0-EXAMPLE.story.md REQ-SAFE-OPERATION\n    await cleanUp();\n  }\n}`,
+                output: `async function example() {\n  // @supports docs/stories/010.0-EXAMPLE.story.md REQ-SAFE-OPERATION\n  try {\n    await doWork();\n  } finally {\n    await cleanUp();\n  }\n}`,
+                errors: [{ messageId: "redundantAnnotation" }],
+            },
             // TODO: rule implementation exists; full invalid-case behavior tests pending refinement
             // {
             //   name: "[REQ-SCOPE-ANALYSIS][REQ-STATEMENT-SIGNIFICANCE] flags redundant annotation on simple return inside annotated if",

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

@@ -8,15 +8,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
+ * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
  * @req REQ-BRANCH-DETECTION - Verify require-branch-annotation rule enforces branch annotations
  * @req REQ-ERROR-SPECIFIC - Branch-level missing-annotation error messages are specific and informative
  * @req REQ-ERROR-CONSISTENCY - Branch-level missing-annotation error messages follow shared conventions
  * @req REQ-ERROR-SUGGESTION - Branch-level missing-annotation errors include suggestions when applicable
  * @req REQ-NESTED-HANDLING - Nested branch annotations are correctly enforced without duplicative reporting
  * @req REQ-SUPPORTS-ALTERNATIVE - Branches annotated only with @supports are treated as fully annotated
+ * @req REQ-PLACEMENT-CONFIG - Rule supports configurable annotation placement modes
+ * @req REQ-DEFAULT-BACKWARD-COMPAT - Default placement remains backward compatible with existing behavior
  * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-BRANCH-DETECTION REQ-NESTED-HANDLING REQ-SUPPORTS-ALTERNATIVE
  * @supports docs/stories/007.0-DEV-ERROR-REPORTING.story.md REQ-ERROR-SPECIFIC REQ-ERROR-CONSISTENCY REQ-ERROR-SUGGESTION
  * @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION-ELSE-IF REQ-FALLBACK-LOGIC-ELSE-IF REQ-POSITION-PRIORITY-ELSE-IF REQ-PRETTIER-AUTOFIX-ELSE-IF
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG REQ-DEFAULT-BACKWARD-COMPAT
  */
 const eslint_1 = require("eslint");
 const require_branch_annotation_1 = __importDefault(require("../../src/rules/require-branch-annotation"));
@@ -184,6 +188,22 @@ if (outer) {
 if (condition) {}`,
                 options: [{ branchTypes: ["IfStatement", "SwitchCase"] }],
             },
+            {
+                name: "[REQ-PLACEMENT-CONFIG][REQ-DEFAULT-BACKWARD-COMPAT] if-statement with before-brace annotations using annotationPlacement: 'before'",
+                code: `// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-PLACEMENT-CONFIG
+if (condition) {}`,
+                options: [{ annotationPlacement: "before" }],
+            },
+            {
+                name: "[REQ-INSIDE-BRACE-PLACEMENT][REQ-PLACEMENT-CONFIG] if-statement annotated inside block under annotationPlacement: 'inside' (Story 028.0)",
+                code: `if (condition) {
+  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+  // @req REQ-INSIDE-BRACE-PLACEMENT
+  doSomething();
+}`,
+                options: [{ annotationPlacement: "inside" }],
+            },
             {
                 name: "[REQ-SUPPORTS-ALTERNATIVE] if-statement with only @supports annotation is treated as fully annotated",
                 code: `// @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-SUPPORTS-ALTERNATIVE
@@ -404,6 +424,22 @@ if (a) {
 }`,
                 errors: makeMissingAnnotationErrors("@story", "@req", "@story", "@req"),
             },
+            {
+                name: "[REQ-INSIDE-BRACE-PLACEMENT][REQ-BEFORE-BRACE-ERROR][REQ-PLACEMENT-CONFIG] before-brace annotations ignored when annotationPlacement: 'inside'",
+                code: `// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+// @req REQ-BEFORE-BRACE-ERROR
+if (condition) {
+  doSomething();
+}`,
+                options: [{ annotationPlacement: "inside" }],
+                output: `// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+// @req REQ-BEFORE-BRACE-ERROR
+if (condition) {
+  // @story <story-file>.story.md
+  doSomething();
+}`,
+                errors: makeMissingAnnotationErrors("@story", "@req"),
+            },
         ],
     });
     runRule({

package/lib/tests/utils/branch-annotation-helpers.test.js

@@ -111,3 +111,55 @@ describe("validateBranchTypes helper (Story 004.0-DEV-BRANCH-ANNOTATIONS)", () =
         expect(loopText).toBe("@story loop branch story loop details");
     });
 });
+/**
+ * Tests for annotationPlacement wiring at helper level
+ * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-DEFAULT-BACKWARD-COMPAT
+ */
+describe("gatherBranchCommentText annotationPlacement wiring (Story 028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION)", () => {
+    it("[REQ-PLACEMENT-CONFIG][REQ-DEFAULT-BACKWARD-COMPAT] honors configured placement for simple if-statements", () => {
+        const sourceCode = {
+            lines: [
+                "function demo() {",
+                "  if (condition) {",
+                "    // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md",
+                "    // @req REQ-INSIDE",
+                "    doSomething();",
+                "  }",
+                "}",
+            ],
+            getCommentsBefore: jest
+                .fn()
+                .mockReturnValue([
+                { value: "@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md" },
+                { value: "@req REQ-BEFORE" },
+            ]),
+        };
+        const ifNode = {
+            type: "IfStatement",
+            loc: {
+                start: { line: 2, column: 2 },
+                end: { line: 5, column: 3 },
+            },
+            consequent: {
+                type: "BlockStatement",
+                loc: {
+                    start: { line: 2, column: 18 },
+                    end: { line: 5, column: 3 },
+                },
+            },
+        };
+        const parent = {
+            type: "BlockStatement",
+            body: [ifNode],
+        };
+        const beforeText = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, ifNode, parent, "before");
+        expect(beforeText).toContain("@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md");
+        expect(beforeText).toContain("@req REQ-BEFORE");
+        const insideText = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, ifNode, parent, "inside");
+        expect(insideText).toContain("@story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md");
+        expect(insideText).toContain("@req REQ-INSIDE");
+        expect(insideText).not.toContain("@req REQ-BEFORE");
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.17.1",
+  "version": "1.19.0",
   "description": "A customizable ESLint plugin that enforces traceability annotations in your code, ensuring each implementation is linked to its requirement or test case.",
   "main": "lib/src/index.js",
   "types": "lib/src/index.d.ts",

package/user-docs/api-reference.md

@@ -290,7 +290,7 @@ The rule accepts an optional configuration object:
 - `requireDescribeStory` (boolean, optional) – When `true` (default), requires that each top-level `describe` block include a story reference somewhere in its description text (for example, a path such as `docs/stories/010.0-PAYMENTS.story.md` or a shorter project-specific alias that your team uses consistently).
 - `requireTestReqPrefix` (boolean, optional) – When `true` (default), requires each `it`/`test` block name to begin with a requirement identifier in square brackets, such as `[REQ-PAYMENTS-REFUND]`. The exact `REQ-` pattern is shared with the `valid-annotation-format` rule’s requirement ID checks.
 - `describePattern` (string, optional) – A JavaScript regular expression **source** (without leading and trailing `/`) that the `describe` description text must match when `requireDescribeStory` is enabled. This lets you enforce a project-specific format such as requiring a canonical story path or a `STORY-` style identifier in the `describe` string. If omitted, the default is equivalent to `"Story [0-9]+\\.[0-9]+-"`, which expects the description to include a story label such as `"Story 021.0-DEV-TEST-TRACEABILITY"`. You can override this to instead require full story paths or whatever story-labeling convention your project prefers.
-- `autoFixTestTemplate` (boolean, optional) – When `true` (default), allows the rule’s `--fix` mode to insert a file-level `@supports` placeholder template at the top of test files that are missing it. The template is intentionally non-semantic and includes TODO-style guidance so humans can later replace it with a real story path and requirement IDs; disabling this option prevents the rule from inserting the template automatically.
+- `autoFixTestTemplate` (boolean, optional) – When `true` (default), allows the rule’s `--fix` mode to insert a file-level `@supports` placeholder template at the top of test files that are missing it. The template is intentionally non-semantic and includes TODO-style guidance so humans can later replace it with a real story and requirement IDs; disabling this option prevents the rule from inserting the template automatically.
 - `autoFixTestPrefixFormat` (boolean, optional) – When `true` (default), enables safe normalization of malformed `[REQ-XXX]` prefixes in `it`/`test` names during `--fix`. The rule only rewrites prefixes that already contain a recognizable requirement identifier and limits changes to formatting concerns (spacing, square brackets vs. parentheses, underscore and dash usage, and letter casing) without fabricating new IDs or guessing requirement names.
 - `testSupportsTemplate` (string, optional) – Overrides the default file-level `@supports` placeholder template used when `autoFixTestTemplate` is enabled. This string should be a complete JSDoc-style block (for example, including `/**`, `*`, and `*/`) that encodes your project’s preferred TODO guidance or placeholder story path; it is inserted verbatim at the top of matching test files that lack a `@supports` annotation, and is never interpreted or expanded by the rule.
 
@@ -327,6 +327,8 @@ describe("Refunds flow docs/stories/010.0-PAYMENTS.story.md", () => {
 
 Description: Detects and optionally removes **redundant** traceability annotations on code that is already covered by an enclosing annotated scope. It focuses on simple, statement-level constructs—such as `return` statements, basic variable declarations, and other leaf statements—where repeating the same `@story` / `@req` / `@supports` information adds noise without improving coverage. When run with `--fix`, the rule offers safe auto-fixes that remove only the redundant comments while preserving all annotations that are required to maintain correct traceability.
 
+Catch blocks are treated as separate execution paths for traceability purposes, and annotations inside a `catch` block that intentionally repeat the requirements of the corresponding `try` path are not considered redundant and are never auto-removed. This behavior was introduced as part of story `027.0-DEV-REDUNDANT-ANNOTATION-DETECTION (Detect and Remove Redundant Annotations)` to avoid false positives on error-handling paths that implement the same requirement as the success path.
+
 The rule is designed to complement the core presence and validation rules: it never treats removing a redundant annotation as valid if doing so would leave the underlying requirement or story **uncovered** according to the plugin’s normal rules. It only targets comments whose traceability content is already implied by a surrounding function, method, or branch annotation.
 
 Options:
@@ -344,6 +346,9 @@ The rule accepts an optional configuration object:
 Behavior notes:
 
 - The rule only inspects comments that contain recognized traceability annotations (`@story`, `@req`, `@supports`) and are attached to simple statements (returns, expression statements, variable declarations, and similar leaf nodes). It intentionally does **not** attempt to de-duplicate annotations on functions, classes, or major branches, which remain the responsibility of the core rules. When a statement has multiple redundant traceability comments (for example, a small comment block that repeats both @story and @req lines), the rule reports a **single** diagnostic for that statement and, in fix mode, removes all of the redundant annotation comments associated with it in a single grouped fix.
+- **Catch blocks and error-handling paths**
+  - The rule never treats annotations inside a `catch` block as redundant, even when they repeat exactly the same `(story, requirement)` pairs that already cover the surrounding `try` statement or other enclosing branches.
+  - This preserves explicit traceability for error-handling logic, in line with the requirements captured in story `027.0-DEV-REDUNDANT-ANNOTATION-DETECTION`, and avoids collapsing success-path and failure-path coverage into a single, less precise annotation.
 - Auto-fix removes only the redundant traceability lines (and any now-empty comment delimiters when safe) while preserving surrounding non-traceability text in the same comment where possible.
 - When no enclosing scope with compatible coverage is found within `maxScopeDepth`, the annotation is not considered redundant and is left unchanged.
 

package/user-docs/examples.md

@@ -187,3 +187,35 @@ Depending on your Prettier version and configuration, the exact layout of the `e
   - For most branch types, `traceability/require-branch-annotation` associates comments immediately before the branch keyword (such as `if`, `else`, `switch`, `case`) with that branch. Branches can be annotated either with a single `@supports` line (preferred), or with the older `@story`/`@req` pair for backward compatibility. The rule treats a valid `@supports` annotation as satisfying both the story and requirement presence checks.
   - For `catch` clauses and `else if` branches, the rule is formatter-aware and also looks at comments between the condition and the block, as well as the first comment-only lines inside the block body, so you do not need to fight Prettier if it moves your annotations.
   - When annotations exist in more than one place around an `else if` branch, the rule prefers comments immediately before the `else if` line, then comments between the condition and the block, and finally comments inside the block body, matching the behavior described in the API reference and stories `025.0` and `026.0`.
+
+## 7. Redundant annotations and catch blocks
+
+When `traceability/no-redundant-annotation` is enabled (for example, via the recommended preset), `catch` blocks are always treated as distinct execution paths. Repeating the same `(story, requirement)` pair in a `catch` block as in the corresponding `try` path is not considered redundant and will be preserved. This behavior is part of the improvements captured in story `027.0-DEV-REDUNDANT-ANNOTATION-DETECTION`.
+
+In the following example, running ESLint with `--fix` will not remove the `@supports` annotation on the `catch` block, even though it repeats the requirement from the `try` path, because it represents separate error-handling coverage.
+
+```js
+function filterSafeVersions(allVersions) {
+  try {
+    const stable = allVersions.filter((v) => !v.includes("-beta"));
+
+    // @supports docs/stories/010.0-EXAMPLE.story.md REQ-SAFE-OPERATION
+    if (stable.length > 0) {
+      return stable;
+    }
+    // @supports docs/stories/010.0-EXAMPLE.story.md REQ-SAFE-OPERATION
+    else if (allVersions.length > 0) {
+      // Fall back to all versions if we have no clearly stable ones
+      return allVersions;
+    }
+
+    // Fallback when the input list is empty
+    return [];
+  } catch (error) {
+    // @supports docs/stories/010.0-EXAMPLE.story.md REQ-SAFE-OPERATION
+    // traceability/no-redundant-annotation keeps this as separate error-handling coverage,
+    // even though it repeats the requirement from the try path.
+    return [];
+  }
+}
+```

package/user-docs/migration-guide.md

@@ -123,7 +123,7 @@ A typical migration path is:
 - Enable it as `"warn"` to get non-breaking guidance and auto-fixes for straightforward cases.
 - Optionally move to `"error"` once you want to strictly enforce `@supports` usage for all JSDoc blocks that are eligible for safe conversion.
 
-#### When to keep `@story` + `@req`
+#### When to keep `@story` + `req`
 
 Keep your current annotations if:
 
@@ -229,6 +229,8 @@ In all cases, the rule is conservative:
 
 The rule operates over both `@supports` and legacy `@story`/`@req` style annotations, so it continues to work even in mixed codebases during a long-running migration.
 
+In addition, `catch` blocks are treated as distinct execution paths: repeating the same `(story, requirement)` pair in a `catch` block is **not** considered redundant, because the error-handling path is typically validated and reasoned about separately from the main control flow.
+
 A simplified example, using an illustrative story path that represents a file in **your** documentation tree:
 
 Before (redundant duplication inside a branch):
@@ -271,6 +273,38 @@ if (cart.items.length === 0) {
 }
 ```
 
+#### Example: try/if/else-if/catch with non-redundant catch annotation
+
+The following example shows a `try` block with an `if` / `else if` chain that validates a safe operation, and a `catch` block that handles the error path for the **same** requirement. Both paths are annotated with the same `(story, requirement)` pair to make it clear that the requirement covers normal execution and error handling:
+
+```js
+async function performSafeOperation(input) {
+  try {
+    // @supports docs/stories/010.0-EXAMPLE.story.md REQ-SAFE-OPERATION
+    if (input == null) {
+      throw new Error("Missing input");
+    }
+
+    // @supports docs/stories/010.0-EXAMPLE.story.md REQ-SAFE-OPERATION
+    if (typeof input === "string") {
+      return await doSafeStringOperation(input);
+    } else if (Array.isArray(input)) {
+      return await doSafeArrayOperation(input);
+    }
+
+    return await doSafeFallbackOperation(input);
+  } catch (error) {
+    // This catch represents the error-handling path for the same safe-operation requirement.
+    // Even though the coverage matches the try/if/else-if chain above, it is *not* redundant:
+    // it documents how failures are handled for the same requirement.
+    // @supports docs/stories/010.0-EXAMPLE.story.md REQ-SAFE-OPERATION
+    return handleSafeOperationFailure(error, input);
+  }
+}
+```
+
+Here, `traceability/no-redundant-annotation` recognizes the `catch` block as a separate execution path from the main `try` body. The annotation in the `catch` remains intact and is **not** treated as redundant, even though it repeats the same `docs/stories/010.0-EXAMPLE.story.md REQ-SAFE-OPERATION` coverage as the guarded `if` / `else if` chain in the `try`. This behavior was introduced and validated as part of story `027.0-DEV-REDUNDANT-ANNOTATION-DETECTION (Detect and Remove Redundant Annotations)` to prevent regressions in real-world `try/if/else-if/catch` scenarios like the one discussed there.
+
 #### Safe migration workflow
 
 To use `traceability/no-redundant-annotation` safely during your v1.x migration: