eslint-plugin-traceability 1.19.3 → 1.20.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [1.19.3](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.19.2...v1.19.3) (2025-12-18)
+# [1.20.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.19.4...v1.20.0) (2025-12-18)
 
 
-### Bug Fixes
+### Features
 
-* support inside placement for switch cases in branch helpers ([3fd08d1](https://github.com/voder-ai/eslint-plugin-traceability/commit/3fd08d1314085a7aa9894f6248dbb7f42a07bda0))
+* extend branch placement standard docs and helpers ([ae05a52](https://github.com/voder-ai/eslint-plugin-traceability/commit/ae05a5232b724060f7b1baae9a6be6eedf466617))
 
 # Changelog
 

package/README.md

@@ -89,6 +89,49 @@ export default [
 ];
 ```
 
+### Annotation Placement
+
+Traceability annotations are typically placed immediately adjacent to the code they index. The plugin exposes explicit placement options for branch-level rules and a stable, conventional placement for function-level rules.
+
+- **Branch-level (`traceability/require-branch-annotation`)**
+
+  `require-branch-annotation` supports an `annotationPlacement` option:
+  - `"before"` – Annotation appears **immediately before** the branch statement (default).
+  - `"inside"` – Annotation appears as the **first comment-only lines inside** the branch block.
+
+  In `"inside"` mode, the rule expects the annotation to be the first meaningful content inside blocks for `if` / `else` / loops / `try` / `catch` / `finally` / `switch` cases.
+
+  Example (`if` statement):
+
+  ```js
+  // annotationPlacement: "before"
+  // @supports docs/stories/auth.md REQ-AUTH-VALIDATION
+  if (isValidUser(user)) {
+    performLogin(user);
+  }
+
+  // annotationPlacement: "inside"
+  if (isValidUser(user)) {
+    // @supports docs/stories/auth.md REQ-AUTH-VALIDATION
+    performLogin(user);
+  }
+  ```
+
+- **Function-level (`traceability/require-story-annotation`, `traceability/require-req-annotation`)**
+
+  Function-level rules continue to accept annotations:
+  - As JSDoc blocks immediately preceding the function, or
+  - As line comments placed directly before the function declaration or expression.
+
+  Function-level rules now support the same placement configuration model as branches:
+  - By default, annotations are still placed immediately before the function (JSDoc or line comments).
+  - When you configure `annotationPlacement: "inside"` on `traceability/require-story-annotation`, the rule prefers annotations as the first comment-only lines inside the function or method body, mirroring the branch-level inside-brace standard from Story 028.0. Declaration-only shapes such as `TSDeclareFunction` and `TSMethodSignature` remain before-function only, since they have no executable body.
+
+For full configuration details and migration guidance between placement styles, see:
+
+- `traceability/require-branch-annotation` rule docs: [docs/rules/require-branch-annotation.md](docs/rules/require-branch-annotation.md)
+- Migration guide: [user-docs/migration-guide.md](user-docs/migration-guide.md)
+
 ### Available Rules
 
 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.

package/lib/src/rules/helpers/require-story-core.js

@@ -139,6 +139,10 @@ function createMissingStoryReportDescriptor(config) {
         ],
     };
 }
+function resolveAnnotationPlacement(options) {
+    const raw = options?.annotationPlacement;
+    return raw === "inside" || raw === "before" ? raw : "before";
+}
 /**
  * Core helper to report a missing @story annotation for a function-like node.
  * This reporting utility delegates behavior to injected dependencies so that
@@ -153,6 +157,11 @@ function createMissingStoryReportDescriptor(config) {
 function coreReportMissing(deps, context, sourceCode, config) {
     const { node, target: passedTarget, options = {} } = config;
     withSafeReporting("coreReportMissing", () => {
+        const annotationPlacement = resolveAnnotationPlacement(options);
+        if (typeof deps.hasStoryAnnotationWithPlacement === "function" &&
+            deps.hasStoryAnnotationWithPlacement(sourceCode, node, annotationPlacement)) {
+            return;
+        }
         if (deps.hasStoryAnnotation(sourceCode, node)) {
             return;
         }

package/lib/src/rules/helpers/require-story-helpers.d.ts

@@ -53,6 +53,7 @@ declare function leadingCommentsHasStory(node: any): boolean;
  * @req REQ-ANNOTATION-REQUIRED - Detect existing story annotations in JSDoc or comments
  */
 declare function hasStoryAnnotation(sourceCode: any, node: any): boolean;
+declare const hasStoryAnnotationWithPlacement: typeof hasStoryAnnotation;
 /**
  * Determine AST node where annotation should be inserted
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -84,4 +85,4 @@ declare function reportMethod(context: Rule.RuleContext, sourceCode: any, config
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED
  */
-export { STORY_PATH, getAnnotationTemplate, shouldApplyAutoFix, isExportedNode, jsdocHasStory, commentsBeforeHasStory, leadingCommentsHasStory, hasStoryAnnotation, getNodeName, extractName, resolveTargetNode, shouldProcessNode, DEFAULT_SCOPE, EXPORT_PRIORITY_VALUES, linesBeforeHasStory, parentChainHasStory, fallbackTextBeforeHasStory, reportMissing, reportMethod, };
+export { STORY_PATH, getAnnotationTemplate, shouldApplyAutoFix, isExportedNode, jsdocHasStory, commentsBeforeHasStory, leadingCommentsHasStory, hasStoryAnnotation, hasStoryAnnotationWithPlacement, getNodeName, extractName, resolveTargetNode, shouldProcessNode, DEFAULT_SCOPE, EXPORT_PRIORITY_VALUES, linesBeforeHasStory, parentChainHasStory, fallbackTextBeforeHasStory, reportMissing, reportMethod, };

package/lib/src/rules/helpers/require-story-helpers.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fallbackTextBeforeHasStory = exports.parentChainHasStory = exports.linesBeforeHasStory = exports.EXPORT_PRIORITY_VALUES = exports.DEFAULT_SCOPE = exports.getNodeName = exports.STORY_PATH = void 0;
+exports.fallbackTextBeforeHasStory = exports.parentChainHasStory = exports.linesBeforeHasStory = exports.EXPORT_PRIORITY_VALUES = exports.DEFAULT_SCOPE = exports.getNodeName = exports.hasStoryAnnotationWithPlacement = exports.STORY_PATH = void 0;
 exports.getAnnotationTemplate = getAnnotationTemplate;
 exports.shouldApplyAutoFix = shouldApplyAutoFix;
 exports.isExportedNode = isExportedNode;
@@ -220,6 +220,9 @@ function hasStoryAnnotation(sourceCode, node) {
     }
     return false;
 }
+// Placement-aware alias reserved for future inside-brace function placement.
+const hasStoryAnnotationWithPlacement = hasStoryAnnotation;
+exports.hasStoryAnnotationWithPlacement = hasStoryAnnotationWithPlacement;
 /**
  * Determine AST node where annotation should be inserted
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md

package/lib/src/rules/require-req-annotation.d.ts

@@ -6,6 +6,10 @@
  * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
  * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of which exports are checked
  * @req REQ-EXPORT-PRIORITY - Allow configuration of export priority behavior
+ *
+ * Note: This rule accepts annotationPlacement for configuration parity with
+ * require-story-annotation, but currently still requires annotations before
+ * the function (no inside-function support yet).
  */
 import type { Rule } from "eslint";
 declare const rule: Rule.RuleModule;

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

@@ -39,6 +39,9 @@ const rule = {
                     exportPriority: {
                         enum: require_story_helpers_1.EXPORT_PRIORITY_VALUES,
                     },
+                    annotationPlacement: {
+                        enum: ["before", "inside"],
+                    },
                 },
                 additionalProperties: false,
             },

package/lib/src/rules/require-story-annotation.d.ts

@@ -17,6 +17,10 @@ import type { Rule } from "eslint";
 /**
  * ESLint rule to require @story annotations on functions/methods.
  *
+ * This rule participates in Story 028.0 placement standardization by supporting
+ * configurable annotation placement, including inside-brace function annotations
+ * when configured.
+ *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md

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

@@ -5,6 +5,10 @@ const require_story_helpers_1 = require("./helpers/require-story-helpers");
 /**
  * ESLint rule to require @story annotations on functions/methods.
  *
+ * This rule participates in Story 028.0 placement standardization by supporting
+ * configurable annotation placement, including inside-brace function annotations
+ * when configured.
+ *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md

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

@@ -53,6 +53,8 @@ export declare function reportMissingStory(context: Rule.RuleContext, node: any,
     storyFixCountRef: {
         count: number;
     };
+    annotationPlacement: AnnotationPlacement;
+    sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>;
 }): void;
 /**
  * Report missing @req annotation tag on a branch node when that branch has no linked requirement identifier in its associated comments.

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

@@ -11,6 +11,7 @@ Object.defineProperty(exports, "reportMissingAnnotations", { enumerable: true, g
 const branch_annotation_loop_helpers_1 = require("./branch-annotation-loop-helpers");
 const branch_annotation_if_helpers_1 = require("./branch-annotation-if-helpers");
 const branch_annotation_switch_helpers_1 = require("./branch-annotation-switch-helpers");
+const branch_annotation_story_fix_helpers_1 = require("./branch-annotation-story-fix-helpers");
 /**
  * Valid branch types for require-branch-annotation rule.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
@@ -402,21 +403,20 @@ function gatherBranchCommentText(sourceCode, node, parent, annotationPlacement =
  * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
  */
 function reportMissingStory(context, node, options) {
-    const { indent, insertPos, storyFixCountRef } = options;
+    const { indent, insertPos, storyFixCountRef, annotationPlacement, sourceCode, } = options;
     /**
      * Conditional branch deciding whether to offer an auto-fix for the missing story.
      * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
      * @req REQ-TRACEABILITY-FIX-DECISION - Trace decision to provide fixer for missing @story
      */
     if (storyFixCountRef.count === 0) {
-        /**
-         * Fixer that inserts a default @story tag above the branch.
-         * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-         * @req REQ-TRACEABILITY-FIX-ARROW - Trace fixer function used to insert missing @story
-         */
-        function insertStoryFixer(fixer) {
-            return fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @story <story-file>.story.md\n`);
-        }
+        const insertStoryFixer = (0, branch_annotation_story_fix_helpers_1.createStoryFixer)({
+            annotationPlacement,
+            sourceCode,
+            node,
+            insertPos,
+            indent,
+        });
         context.report({
             node,
             messageId: "missingAnnotation",

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

@@ -0,0 +1,52 @@
+import type { Rule } from "eslint";
+import type { AnnotationPlacement } from "./branch-annotation-helpers";
+/**
+ * Shared helpers for computing inside-brace indentation and insert positions
+ * for branch nodes used by require-branch-annotation. This module isolates
+ * the inside-placement logic so that the main report helpers stay small and
+ * within ESLint's max-lines-per-function limits.
+ *
+ * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+ * @supports REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG REQ-INDENTATION-CORRECT
+ */
+type SourceCode = ReturnType<Rule.RuleContext["getSourceCode"]>;
+type IndentHelperContext = {
+    getInsideBlockIndentAndInsertPos: (_sourceCode: SourceCode, _blockNode: any, _baseFallbackIndent: string) => {
+        indent: string;
+        insertPos: number;
+    };
+    getIndentAndInsertPosForLine: (_sourceCode: SourceCode, _line: number, _fallbackIndent: string) => {
+        indent: string;
+        insertPos: number;
+    };
+};
+type BranchIndentOptions = {
+    sourceCode: SourceCode;
+    node: any;
+    indent: string;
+};
+/**
+ * Inside-placement helper used by getBaseBranchIndentAndInsertPos to select the
+ * correct inside-placement strategy for the base branch.
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG
+ */
+export declare function computeInsideBaseIndentAndInsertPos(options: {
+    sourceCode: SourceCode;
+    node: any;
+    annotationPlacement: AnnotationPlacement;
+    currentIndent: string;
+}, context: IndentHelperContext): {
+    indent: string;
+    insertPos: number;
+} | null;
+/**
+ * Apply inside-placement overrides for non-if branches (switch, try, loops, catch).
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG
+ */
+export declare function applyInsidePlacementOverridesForBranch(options: BranchIndentOptions & {
+    annotationPlacement: AnnotationPlacement;
+}, context: IndentHelperContext): {
+    indent: string;
+    insertPos: number;
+} | null;
+export {};

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

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeInsideBaseIndentAndInsertPos = computeInsideBaseIndentAndInsertPos;
+exports.applyInsidePlacementOverridesForBranch = applyInsidePlacementOverridesForBranch;
+function isLoopNode(node) {
+    return (node.type === "ForStatement" ||
+        node.type === "ForInStatement" ||
+        node.type === "ForOfStatement" ||
+        node.type === "WhileStatement" ||
+        node.type === "DoWhileStatement");
+}
+function computeInsideCatchIndentAndInsertPos(sourceCode, node, currentIndent, context) {
+    if (!(node.type === "CatchClause" && node.body)) {
+        return null;
+    }
+    const bodyNode = node.body;
+    if (!bodyNode.loc || !bodyNode.loc.start) {
+        return null;
+    }
+    return context.getInsideBlockIndentAndInsertPos(sourceCode, bodyNode, currentIndent);
+}
+function computeInsideLoopIndentAndInsertPos(options, context) {
+    const { sourceCode, node, indent } = options;
+    if (!isLoopNode(node) ||
+        !node.body ||
+        node.body.type !== "BlockStatement" ||
+        !node.body.loc ||
+        !node.body.loc.start) {
+        return null;
+    }
+    return context.getInsideBlockIndentAndInsertPos(sourceCode, node.body, indent);
+}
+function computeInsideTryOrSwitchIndentAndInsertPos(sourceCode, node, currentIndent, context) {
+    if (!((node.type === "TryStatement" || node.type === "SwitchCase") &&
+        node.consequent &&
+        Array.isArray(node.consequent) &&
+        node.consequent.length > 0)) {
+        return null;
+    }
+    const firstStatement = node.consequent[0];
+    if (!firstStatement || !firstStatement.loc || !firstStatement.loc.start) {
+        return null;
+    }
+    const commentLineInfo = context.getIndentAndInsertPosForLine(sourceCode, firstStatement.loc.start.line, currentIndent);
+    return {
+        indent: commentLineInfo.indent,
+        insertPos: commentLineInfo.insertPos,
+    };
+}
+function computeInsideTryBlockIndentAndInsertPos(options, context) {
+    const { sourceCode, node, indent } = options;
+    if (!(node.type === "TryStatement" &&
+        node.block &&
+        node.block.type === "BlockStatement" &&
+        node.block.loc &&
+        node.block.loc.start)) {
+        return null;
+    }
+    return context.getInsideBlockIndentAndInsertPos(sourceCode, node.block, indent);
+}
+function computeInsideSwitchCaseIndentAndInsertPos(options, context) {
+    const { sourceCode, node, indent } = options;
+    if (!(node.type === "SwitchCase" &&
+        node.consequent &&
+        Array.isArray(node.consequent) &&
+        node.consequent.length > 0)) {
+        return null;
+    }
+    const firstStatement = node.consequent[0];
+    if (!firstStatement || !firstStatement.loc || !firstStatement.loc.start) {
+        return null;
+    }
+    // Prefer line-based helper for consistency with other callers.
+    const commentLineInfo = context.getIndentAndInsertPosForLine(sourceCode, firstStatement.loc.start.line, indent);
+    return {
+        indent: commentLineInfo.indent,
+        insertPos: commentLineInfo.insertPos,
+    };
+}
+function computeInsideCatchBlockIndentAndInsertPos(options, context) {
+    const { sourceCode, node, indent } = options;
+    if (!(node.type === "CatchClause" &&
+        node.body &&
+        node.body.type === "BlockStatement" &&
+        node.body.loc &&
+        node.body.loc.start)) {
+        return null;
+    }
+    return context.getInsideBlockIndentAndInsertPos(sourceCode, node.body, indent);
+}
+/**
+ * Inside-placement helper used by getBaseBranchIndentAndInsertPos to select the
+ * correct inside-placement strategy for the base branch.
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG
+ */
+function computeInsideBaseIndentAndInsertPos(options, context) {
+    const { sourceCode, node, annotationPlacement, currentIndent } = options;
+    if (annotationPlacement !== "inside") {
+        return null;
+    }
+    const catchInside = computeInsideCatchIndentAndInsertPos(sourceCode, node, currentIndent, context);
+    if (catchInside) {
+        return catchInside;
+    }
+    const loopInside = computeInsideLoopIndentAndInsertPos({ sourceCode, node, indent: currentIndent }, context);
+    if (loopInside) {
+        return loopInside;
+    }
+    const tryOrSwitchInside = computeInsideTryOrSwitchIndentAndInsertPos(sourceCode, node, currentIndent, context);
+    if (tryOrSwitchInside) {
+        return tryOrSwitchInside;
+    }
+    return null;
+}
+/**
+ * Apply inside-placement overrides for non-if branches (switch, try, loops, catch).
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG
+ */
+function applyInsidePlacementOverridesForBranch(options, context) {
+    const { annotationPlacement } = options;
+    if (annotationPlacement !== "inside") {
+        return null;
+    }
+    const calculators = [
+        computeInsideSwitchCaseIndentAndInsertPos,
+        computeInsideTryBlockIndentAndInsertPos,
+        computeInsideLoopIndentAndInsertPos,
+        computeInsideCatchBlockIndentAndInsertPos,
+    ];
+    for (const calculator of calculators) {
+        const result = calculator(options, context);
+        if (result) {
+            return result;
+        }
+    }
+    return null;
+}

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/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-SUPPORTS-ALTERNATIVE
  * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
  */
 export declare function reportMissingAnnotations(context: Rule.RuleContext, node: any, storyFixCountRef: {

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.reportMissingAnnotations = reportMissingAnnotations;
 const branch_annotation_helpers_1 = require("./branch-annotation-helpers");
+const branch_annotation_indent_helpers_1 = require("./branch-annotation-indent-helpers");
 /**
  * Compute indentation and insert position for the start of a given 1-based line
  * number. This keeps indentation and fixer insert positions consistent across
@@ -23,11 +24,43 @@ function getIndentAndInsertPosForLine(sourceCode, line, fallbackIndent) {
     return { indent, insertPos };
 }
 /**
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
+ * Compute indentation and insert position for the first "inner" line of a
+ * BlockStatement, used for inside-brace insertion.
+ * Falls back to the block's own line with one extra indent step if it has no
+ * body statements.
  */
-function getBaseBranchIndentAndInsertPos(sourceCode, node, _annotationPlacement) {
-    let { indent, insertPos } = getIndentAndInsertPosForLine(sourceCode, node.loc.start.line, "");
+function getInsideBlockIndentAndInsertPos(sourceCode, blockNode, baseFallbackIndent) {
+    let indent = baseFallbackIndent;
+    let insertPos = sourceCode.getIndexFromLoc({
+        line: blockNode.loc.start.line,
+        column: 0,
+    });
+    const bodyStatements = Array.isArray(blockNode.body)
+        ? blockNode.body
+        : undefined;
+    const firstStatement = bodyStatements && bodyStatements.length > 0 ? bodyStatements[0] : undefined;
+    if (firstStatement && firstStatement.loc && firstStatement.loc.start) {
+        const firstLine = firstStatement.loc.start.line;
+        const firstLineInfo = getIndentAndInsertPosForLine(sourceCode, firstLine, baseFallbackIndent);
+        indent = firstLineInfo.indent;
+        insertPos = firstLineInfo.insertPos;
+    }
+    else if (blockNode.loc && blockNode.loc.start) {
+        const blockLine = blockNode.loc.start.line;
+        const blockLineInfo = getIndentAndInsertPosForLine(sourceCode, blockLine, baseFallbackIndent);
+        const innerIndent = `${blockLineInfo.indent}  `;
+        indent = innerIndent;
+        insertPos = blockLineInfo.insertPos;
+    }
+    return { indent, insertPos };
+}
+/**
+ * Apply the base catch-clause indentation/insert-position fallback used by
+ * getBaseBranchIndentAndInsertPos when no inside-placement override is applied.
+ */
+function applyCatchClauseBaseIndentFallback(sourceCode, node, currentIndent, currentInsertPos) {
+    let indent = currentIndent;
+    let insertPos = currentInsertPos;
     if (node.type === "CatchClause" && node.body) {
         const bodyNode = node.body;
         const bodyStatements = Array.isArray(bodyNode.body)
@@ -52,6 +85,27 @@ function getBaseBranchIndentAndInsertPos(sourceCode, node, _annotationPlacement)
     }
     return { indent, insertPos };
 }
+/**
+ * @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, "");
+    const indentHelpers = {
+        getInsideBlockIndentAndInsertPos,
+        getIndentAndInsertPosForLine,
+    };
+    const insideBase = (0, branch_annotation_indent_helpers_1.computeInsideBaseIndentAndInsertPos)({
+        sourceCode,
+        node,
+        annotationPlacement,
+        currentIndent: indent,
+    }, indentHelpers);
+    if (insideBase) {
+        return insideBase;
+    }
+    return applyCatchClauseBaseIndentFallback(sourceCode, node, indent, insertPos);
+}
 /**
  * Determine whether a node represents an else-if branch that should be used for
  * determining comment insertion position.
@@ -112,7 +166,8 @@ function getBranchMissingFlags(sourceCode, node, parent, annotationPlacement) {
  * @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);
+    const base = getBaseBranchIndentAndInsertPos(sourceCode, node, annotationPlacement);
+    let { indent, insertPos } = base;
     if (node.type === "IfStatement") {
         const context = { indent, insertPos };
         const updatedContext = getIfStatementIndentAndInsertPos(sourceCode, node, { parent, annotationPlacement }, context);
@@ -121,6 +176,19 @@ function getBranchIndentAndInsertPos(sourceCode, node, parent, annotationPlaceme
             insertPos: updatedContext.insertPos,
         };
     }
+    const indentHelpers = {
+        getInsideBlockIndentAndInsertPos,
+        getIndentAndInsertPosForLine,
+    };
+    const insideOverride = (0, branch_annotation_indent_helpers_1.applyInsidePlacementOverridesForBranch)({
+        sourceCode,
+        node,
+        indent,
+        annotationPlacement,
+    }, indentHelpers);
+    if (insideOverride) {
+        return insideOverride;
+    }
     return { indent, insertPos };
 }
 /**
@@ -137,12 +205,22 @@ function getBranchAnnotationInfo(sourceCode, node, parent, annotationPlacement)
     const { indent, insertPos } = getBranchIndentAndInsertPos(sourceCode, node, parent, annotationPlacement);
     return { missingStory, missingReq, indent, insertPos };
 }
+function processMissingAnnotationActions(context, node, actions) {
+    /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
+    function processAction(item) {
+        if (item.missing) {
+            item.fn(...item.args);
+        }
+    }
+    actions.forEach(processAction);
+}
 /**
  * Report missing annotations on 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 reportMissingAnnotations(context, node, storyFixCountRef) {
@@ -159,7 +237,17 @@ function reportMissingAnnotations(context, node, storyFixCountRef) {
         {
             missing: missingStory,
             fn: branch_annotation_helpers_1.reportMissingStory,
-            args: [context, node, { indent, insertPos, storyFixCountRef }],
+            args: [
+                context,
+                node,
+                {
+                    indent,
+                    insertPos,
+                    storyFixCountRef,
+                    annotationPlacement,
+                    sourceCode,
+                },
+            ],
         },
         {
             missing: missingReq,
@@ -167,11 +255,5 @@ function reportMissingAnnotations(context, node, storyFixCountRef) {
             args: [context, node, { indent, insertPos, missingStory }],
         },
     ];
-    /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
-    function processAction(item) {
-        if (item.missing) {
-            item.fn(...item.args);
-        }
-    }
-    actions.forEach(processAction);
+    processMissingAnnotationActions(context, node, actions);
 }

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

@@ -0,0 +1,27 @@
+import type { Rule } from "eslint";
+import type { AnnotationPlacement } from "./branch-annotation-helpers";
+/**
+ * Context object for building story-fixers used by require-branch-annotation.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG REQ-INSIDE-BRACE-PLACEMENT
+ */
+export interface StoryFixContext {
+    annotationPlacement: AnnotationPlacement;
+    sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>;
+    node: any;
+    insertPos: number;
+    indent: string;
+}
+/**
+ * Create a fixer function that inserts or migrates a @story comment for a
+ * missing branch annotation, honoring the configured placement mode.
+ * When annotationPlacement is "inside", this helper uses
+ * buildInsidePlacementStoryFixes to migrate existing before-branch
+ * annotations into the standardized inside-brace location. Otherwise, it
+ * preserves the original "before" behavior of inserting directly above
+ * the branch.
+ *
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-AUTO-FIX-MIGRATION REQ-INDENTATION-CORRECT
+ */
+export declare function createStoryFixer(ctx: StoryFixContext): (fixer: any) => any;

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

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStoryFixer = createStoryFixer;
+/**
+ * Build the individual fixes needed when migrating existing before-branch
+ * annotations into inside-brace placement. This helper is responsible for
+ * removing redundant before-branch comments that already contain
+ * traceability tags and inserting the canonical placeholder inside the
+ * branch body at the computed insertion position.
+ *
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-AUTO-FIX-MIGRATION REQ-INSIDE-BRACE-PLACEMENT
+ */
+function buildInsidePlacementStoryFixes(ctx, fixer) {
+    const { sourceCode, node, insertPos, indent } = ctx;
+    const fixes = [];
+    const beforeComments = sourceCode.getCommentsBefore(node) || [];
+    const removableComments = beforeComments.filter((c) => /@story\b/.test(c.value) ||
+        /@req\b/.test(c.value) ||
+        /@supports\b/.test(c.value));
+    removableComments.forEach((comment) => {
+        fixes.push(fixer.remove(comment));
+    });
+    fixes.push(fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @story <story-file>.story.md\n`));
+    return fixes;
+}
+/**
+ * Create a fixer function that inserts or migrates a @story comment for a
+ * missing branch annotation, honoring the configured placement mode.
+ * When annotationPlacement is "inside", this helper uses
+ * buildInsidePlacementStoryFixes to migrate existing before-branch
+ * annotations into the standardized inside-brace location. Otherwise, it
+ * preserves the original "before" behavior of inserting directly above
+ * the branch.
+ *
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-AUTO-FIX-MIGRATION REQ-INDENTATION-CORRECT
+ */
+function createStoryFixer(ctx) {
+    const { annotationPlacement, insertPos, indent } = ctx;
+    function insertStoryFixer(fixer) {
+        if (annotationPlacement === "inside") {
+            return buildInsidePlacementStoryFixes(ctx, fixer);
+        }
+        return fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @story <story-file>.story.md\n`);
+    }
+    return insertStoryFixer;
+}

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

@@ -0,0 +1,23 @@
+import type { Rule } from "eslint";
+/**
+ * Determine whether a function-like node can support inside-brace
+ * placement semantics. Only nodes with a concrete BlockStatement body are
+ * eligible; TypeScript declarations and signature-only nodes are
+ * intentionally excluded.
+ *
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-ALL-BLOCK-TYPES
+ */
+export declare function supportsInsidePlacementForFunction(node: any): boolean;
+/**
+ * Gather the concatenated comment text from the first contiguous
+ * comment-only lines inside a function body. When no such comments are
+ * present or the node has no block body, an empty string is returned.
+ *
+ * This mirrors the branch helpers' behaviour for inside-brace placement
+ * (for example, simple if-statements and switch cases) so that
+ * function-level rules can share the same mental model: annotations live
+ * on the first comment-only line(s) inside the body braces.
+ *
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT REQ-ALL-BLOCK-TYPES
+ */
+export declare function getFunctionInsideBodyCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any): string;

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

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.supportsInsidePlacementForFunction = supportsInsidePlacementForFunction;
+exports.getFunctionInsideBodyCommentText = getFunctionInsideBodyCommentText;
+const branch_annotation_helpers_1 = require("./branch-annotation-helpers");
+/**
+ * Helpers for determining function-body annotation placement.
+ *
+ * These utilities are shared between the function-level traceability rules
+ * (require-story-annotation, require-req-annotation) so they can honour the
+ * same "inside" placement semantics used by branch rules when
+ * `annotationPlacement: "inside"` is configured.
+ *
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-ALL-BLOCK-TYPES REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG
+ */
+/**
+ * Locate the BlockStatement that represents the executable body of a
+ * function-like construct. Returns null when the node has no block body
+ * (for example, TypeScript declarations or arrow functions with
+ * expression bodies).
+ *
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-ALL-BLOCK-TYPES
+ */
+function getFunctionBodyBlock(node) {
+    if (!node || typeof node.type !== "string") {
+        return null;
+    }
+    if (node.type === "FunctionDeclaration" ||
+        node.type === "FunctionExpression" ||
+        node.type === "ArrowFunctionExpression") {
+        const body = node.body;
+        return body && body.type === "BlockStatement" ? body : null;
+    }
+    if (node.type === "MethodDefinition") {
+        const value = node.value;
+        if (value && value.type === "FunctionExpression") {
+            const body = value.body;
+            return body && body.type === "BlockStatement" ? body : null;
+        }
+    }
+    return null;
+}
+/**
+ * Determine whether a function-like node can support inside-brace
+ * placement semantics. Only nodes with a concrete BlockStatement body are
+ * eligible; TypeScript declarations and signature-only nodes are
+ * intentionally excluded.
+ *
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-ALL-BLOCK-TYPES
+ */
+function supportsInsidePlacementForFunction(node) {
+    return !!getFunctionBodyBlock(node);
+}
+/**
+ * Gather the concatenated comment text from the first contiguous
+ * comment-only lines inside a function body. When no such comments are
+ * present or the node has no block body, an empty string is returned.
+ *
+ * This mirrors the branch helpers' behaviour for inside-brace placement
+ * (for example, simple if-statements and switch cases) so that
+ * function-level rules can share the same mental model: annotations live
+ * on the first comment-only line(s) inside the body braces.
+ *
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT REQ-ALL-BLOCK-TYPES
+ */
+function getFunctionInsideBodyCommentText(sourceCode, node) {
+    const block = getFunctionBodyBlock(node);
+    if (!block ||
+        !block.loc ||
+        !block.loc.start ||
+        !block.loc.end ||
+        typeof block.loc.start.line !== "number" ||
+        typeof block.loc.end.line !== "number") {
+        return "";
+    }
+    const getCommentsInside = sourceCode.getCommentsInside;
+    if (typeof getCommentsInside === "function") {
+        try {
+            const insideComments = getCommentsInside(block) || [];
+            const insideText = insideComments
+                .filter((c) => c && typeof c.value === "string")
+                .map((c) => c.value)
+                .join(" ");
+            if (insideText) {
+                return insideText;
+            }
+        }
+        catch {
+            // Fall through to the line-based fallback when structured comment
+            // retrieval is unavailable or fails.
+        }
+    }
+    const lines = sourceCode.lines;
+    if (!Array.isArray(lines)) {
+        return "";
+    }
+    const startIndex = block.loc.start.line - 1;
+    const endIndex = block.loc.end.line - 1;
+    const insideText = (0, branch_annotation_helpers_1.scanCommentLinesInRange)(lines, startIndex + 1, endIndex);
+    return insideText || "";
+}

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

@@ -473,16 +473,7 @@ try {
   handleError(error);
 }`,
                 options: [{ annotationPlacement: "inside" }],
-                output: `// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-// @req REQ-BRANCH-TRY
-// @story <story-file>.story.md
-try {
-  doSomething();
-} catch (error) {
-  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
-  // @req REQ-INSIDE-CATCH
-  handleError(error);
-}`,
+                output: "\n\ntry {\n  // @story <story-file>.story.md\n  doSomething();\n} catch (error) {\n  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md\n  // @req REQ-INSIDE-CATCH\n  handleError(error);\n}",
                 errors: makeMissingAnnotationErrors("@story", "@req"),
             },
             {
@@ -493,12 +484,7 @@ 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();
-}`,
+                output: "\n\nif (condition) {\n  // @story <story-file>.story.md\n  doSomething();\n}",
                 errors: makeMissingAnnotationErrors("@story", "@req"),
             },
             {
@@ -509,12 +495,7 @@ for (const item of items) {
   process(item);
 }`,
                 options: [{ annotationPlacement: "inside" }],
-                output: `// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
-// @req REQ-LOOP-BEFORE
-// @story <story-file>.story.md
-for (const item of items) {
-  process(item);
-}`,
+                output: "\n\nfor (const item of items) {\n  // @story <story-file>.story.md\n  process(item);\n}",
                 errors: makeMissingAnnotationErrors("@story", "@req"),
             },
             {
@@ -530,17 +511,7 @@ catch (error) {
   handleError(error);
 }`,
                 options: [{ annotationPlacement: "inside" }],
-                output: `// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-// @req REQ-BRANCH-TRY
-// @story <story-file>.story.md
-try {
-  doSomething();
-}
-// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
-// @req REQ-CATCH-BEFORE
-catch (error) {
-  handleError(error);
-}`,
+                output: "\n\ntry {\n  // @story <story-file>.story.md\n  doSomething();\n}\n// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md\n// @req REQ-CATCH-BEFORE\ncatch (error) {\n  handleError(error);\n}",
                 errors: makeMissingAnnotationErrors("@story", "@req", "@story", "@req"),
             },
             {
@@ -553,14 +524,7 @@ try {
   cleanup();
 }`,
                 options: [{ annotationPlacement: "inside" }],
-                output: `// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
-// @req REQ-TRY-BEFORE
-// @story <story-file>.story.md
-try {
-  doWork();
-} finally {
-  cleanup();
-}`,
+                output: "\n\ntry {\n  // @story <story-file>.story.md\n  doWork();\n} finally {\n  cleanup();\n}",
                 errors: makeMissingAnnotationErrors("@story", "@req"),
             },
             {
@@ -576,17 +540,7 @@ else if (b) {
   doB();
 }`,
                 options: [{ annotationPlacement: "inside" }],
-                output: `if (a) {
-  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
-  // @req REQ-OUTER-IF-INSIDE
-  doA();
-}
-// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
-// @req REQ-ELSE-IF-BEFORE
-else if (b) {
-  // @story <story-file>.story.md
-  doB();
-}`,
+                output: "if (a) {\n  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md\n  // @req REQ-OUTER-IF-INSIDE\n  doA();\n}\n// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md\n// @req REQ-ELSE-IF-BEFORE\nelse if (b) {\n  // @story <story-file>.story.md\n  doB();\n}",
                 errors: makeMissingAnnotationErrors("@story", "@req"),
             },
             {
@@ -603,18 +557,7 @@ if (a) {
   doC();
 }`,
                 options: [{ annotationPlacement: "inside" }],
-                output: `// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
-// @req REQ-INSIDE-OUTER-IF
-if (a) {
-  // @story <story-file>.story.md
-  doA();
-} else if (b) {
-  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
-  // @req REQ-INSIDE-ELSE-IF
-  doB();
-} else {
-  doC();
-}`,
+                output: "\n\nif (a) {\n  // @story <story-file>.story.md\n  doA();\n} else if (b) {\n  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md\n  // @req REQ-INSIDE-ELSE-IF\n  doB();\n} else {\n  doC();\n}",
                 errors: makeMissingAnnotationErrors("@story", "@req"),
             },
             {
@@ -627,14 +570,7 @@ if (a) {
   }
 }`,
                 options: [{ annotationPlacement: "inside" }],
-                output: `switch (value) {
-  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
-  // @req REQ-SWITCH-BEFORE
-  // @story <story-file>.story.md
-  case 'a': {
-    doSomething();
-  }
-}`,
+                output: "switch (value) {\n  \n  \n  // @story <story-file>.story.md\n  case 'a': {\n    doSomething();\n  }\n}",
                 errors: makeMissingAnnotationErrors("@story", "@req"),
             },
         ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.19.3",
+  "version": "1.20.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

@@ -26,7 +26,7 @@ For function-level traceability, the plugin exposes a unified rule and two legac
 - `traceability/require-traceability` is the **canonical function-level rule** for new configurations. It ensures functions and methods have both story coverage and requirement coverage, and it accepts either `@supports` (preferred) or legacy `@story` / `@req` annotations.
 - `traceability/require-story-annotation` and `traceability/require-req-annotation` are **backward-compatible aliases** that focus on the story and requirement aspects separately. They are retained for existing configurations and share the same underlying implementation model as the unified rule, but new ESLint configs should normally rely on `traceability/require-traceability` rather than enabling these legacy keys directly.
 
-All three rule keys can still be configured individually if you need fine-grained control (for example, to tune severities separately), but the recommended and strict presets enable `traceability/require-traceability` by default and keep the legacy keys primarily for projects that adopted them before the unified rule existed.
+All three rule keys can still be configured individually if you need fine-grained control (for example, to tune severities separately), but the recommended and strict presets enable `traceability/require-traceability` by default and keep the legacy keys primarily for projects that adopted them before the unified rule existed. When the underlying function rules are configured with `annotationPlacement: "inside"`, the unified `require-traceability` rule honours inside-brace placement for function and method bodies in the same formatter-aware way that `require-branch-annotation` handles branches.
 
 ### traceability/require-traceability
 
@@ -44,6 +44,7 @@ Options:
 - `methodAnnotationTemplate` (string, optional) – Overrides the default placeholder JSDoc used when inserting missing `@story` annotations for class methods and TypeScript method signatures. When omitted or blank, falls back to `annotationTemplate` if provided, otherwise the built-in template.
 - `autoFix` (boolean, optional) – When set to `false`, disables all automatic fix behavior for this rule while retaining its suggestions and diagnostics. When omitted or `true`, the rule behaves as before, inserting placeholder annotations in `--fix` mode.
 - `excludeTestCallbacks` (boolean, optional) – When `true` (default), excludes anonymous arrow functions that are direct callbacks to common test framework functions (for example, Jest/Mocha/Vitest `describe`/`it`/`test`/`beforeEach`/`afterEach`/`beforeAll`/`afterAll`, plus focused/skipped/concurrent variants such as `fdescribe`, `xdescribe`, `fit`, `xit`, `test.concurrent`, `describe.concurrent`) from function-level annotation requirements. This assumes those test files are already covered by file-level `@supports` annotations and `traceability/require-test-traceability`. When set to `false`, these callbacks are treated like any other arrow function and must be annotated when in-scope.
+- `annotationPlacement` ("before" | "inside", optional) – Controls whether the rule looks for annotations immediately before functions (`"before"`, the default and backward-compatible behaviour) or allows annotations as the first comment-only lines inside function and method bodies (`"inside"`). In inside mode, the rule continues to treat TypeScript declarations and signature-only nodes (such as `TSDeclareFunction` and `TSMethodSignature`) as before-function only, since they have no executable body.
 
 Default Severity: `error`
 Example:
@@ -70,6 +71,7 @@ Options:
 
 - `scope` (string[], optional) – Controls which function-like node types are required to have @req annotations. Allowed values: "FunctionDeclaration", "FunctionExpression", "MethodDefinition", "TSDeclareFunction", "TSMethodSignature". Default: ["FunctionDeclaration", "FunctionExpression", "MethodDefinition", "TSDeclareFunction", "TSMethodSignature"].
 - `exportPriority` ("all" | "exported" | "non-exported", optional) – Controls whether the rule checks all functions, only exported ones, or only non-exported ones. Default: "all".
+- `annotationPlacement` ("before" | "inside", optional) – Accepted for configuration parity with `require-story-annotation`; requirement annotations are still evaluated using before-function comments and JSDoc today, so `"inside"` does not change behaviour yet.
 
 Default Severity: `error`
 Example (with both `@story` and `@req`, as typically used when both rules are enabled):
@@ -113,7 +115,7 @@ Behavior notes:
 Placement modes:
 
 - `"before"` mode preserves the existing semantics described above, including the dual-position behavior for `catch` and `else if` branches where comments immediately before the branch and the first comment-only lines inside the block are both acceptable and validated according to their existing precedence rules.
-- `"inside"` mode standardizes on the first comment-only lines inside supported branch blocks (`if`/`else if`, loops, `catch`, and `try`) for validation and auto-fix insertion. This placement is designed to work well with Prettier and other formatters, while the current implementation still treats many before-branch annotations as needing migration and may, in corner cases where it cannot confidently rewrite placement, insert new placeholder comments above the branch rather than moving existing ones.
+- `"inside"` mode standardizes on the first comment-only lines inside supported branch blocks (`if`/`else if`, loops, `catch`, and `try`) for validation and auto-fix insertion. This placement is designed to work well with Prettier and other formatters, while the current implementation still treats many before-branch annotations as needing migration and may, in corner cases where it cannot confidently rewrite placement, insert new placeholder comments above the branch rather than moving existing ones. Story `028.0-DEV-FUNCTION-PLACEMENT` also extends this inside-brace standard to function and method bodies via `require-story-annotation` when configured, so projects can apply a single inside-brace rule consistently to both branches and functions.
 
 For a concrete illustration of how these rules interact with Prettier, see the formatter-aware if/else/else-if example in [user-docs/examples.md](examples.md) (section **6. Branch annotations with if/else/else-if and Prettier**), which shows both the hand-written and formatted code that the rule considers valid.
 
@@ -811,4 +813,5 @@ If `--from` or `--to` is missing, the CLI prints an error, shows the help text,
 In CI:
 
 ```bash
-npm run traceability:verify
+npm run traceability:verify
+```

package/user-docs/migration-guide.md

@@ -354,6 +354,46 @@ The full API reference documents all options, but the most important knobs for m
 
 For most teams, the defaults in the recommended preset are a good starting point; you can then tune these options incrementally as your traceability style and `@supports` usage stabilize.
 
+### 3.4 Inside-brace branch annotation placement (optional)
+
+Story 028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION introduces an **inside-brace** placement standard for branch annotations. Instead of placing annotations directly above a branch, you can configure `traceability/require-branch-annotation` to look for annotations as the first comment-only lines **inside** each block body.
+
+The feature is controlled by the `annotationPlacement` option on `require-branch-annotation`:
+
+```js
+// eslint.config.js (flat config example)
+import traceability from "eslint-plugin-traceability";
+
+export default [
+  traceability.configs.recommended,
+  {
+    rules: {
+      "traceability/require-branch-annotation": [
+        "error",
+        {
+          annotationPlacement: "inside", // "before" (default) or "inside"
+        },
+      ],
+    },
+  },
+];
+```
+
+With `annotationPlacement: "inside"`, the rule expects annotations in these locations:
+
+- `if` / `else if` / `else`: first comment-only lines inside the `{ ... }` block.
+- Loops: first comment-only lines inside the loop body.
+- `try` / `catch` / `finally`: first comment-only lines inside the corresponding block body.
+- `switch` cases: first comment-only lines inside the `case` body when it is a block (`case 'a': { ... }`).
+
+Before-brace annotations are still honored when you leave `annotationPlacement` at the default value (`"before"`), so you can migrate gradually:
+
+1. **Start in default mode** — keep `annotationPlacement` unspecified (or set to `"before"`) and continue using your existing `// @story` / `// @req` comments above branches.
+2. **Introduce inside-brace style for new code** — when adding or refactoring branches, place annotations on the first comment-only line inside the block body. This layout plays nicely with Prettier and is what the rule’s auto-fix uses for `if`/`else if` and similar branches.
+3. **Opt-in to `annotationPlacement: "inside"`** — once your codebase is mostly using inside-brace annotations, enable the option. Branches that still rely only on before-brace comments will be reported as missing annotations in inside mode, and the rule’s autofix can insert placeholders at the correct inside location to help you complete the migration.
+
+The default configuration in 1.x keeps `annotationPlacement` at `"before"` for backward compatibility, so existing projects do not need to change anything unless they want the new inside-brace behavior.
+
 ## 4. Test and Validate
 
 Run your test suite to confirm everything passes: