Documentation/clear specification item id terminology

doc/changes/changes_0.10.0.md

@@ -1,11 +1,13 @@
 # OpenFastTrace IntelliJ Plugin 0.10.0, released 2026-07-04
 
 We also updated the bundled OFT to 4.8.0 so tag filters now work end to end instead of being ignored.
+The Test Runner UI now marks transitive defects with a leading `↳` so they stand out from direct defects in the result tree.
 
 ## Bundled OpenFastTrace
 
 OpenFastTrace 4.8.0
 
 ## Bugfix
 
-* #39: Re-enabled tag filter test
+* #39: Re-enabled tag filter test
+* #66: Transitive defects now use a visible `↳` prefix in the Test Runner UI

doc/design/building_block_view.md

@@ -252,7 +252,7 @@ Needs: impl
 ### Specification Item Navigation
 `dsn~specification-item-navigation~1`
 
-The plugin exposes indexed OpenFastTrace specification item declarations through the IntelliJ navigation facilities so users can find declarations through `Go to Symbol` and the Symbols tab in `Search Everywhere`, invoke `Go To Declaration` from `Covers:` entries and from either side of coverage tags, and invoke `Go To Implementations` on a declaration to see coverage-providing occurrences. For shortened left sides of coverage tags, the navigation component resolves the effective covering item ID by inheriting missing name and revision parts from the covered ID on the right side before opening the corresponding declaration.
+The plugin exposes indexed OpenFastTrace specification item declarations through the IntelliJ navigation facilities so users can find declarations through `Go to Symbol` and the Symbols tab in `Search Everywhere`, invoke `Go To Declaration` from `Covers:` entries and from either side of coverage tags, and invoke `Go To Implementations` on a declaration to see coverage-providing occurrences. For shortened left sides of coverage tags, the navigation component resolves the effective covering item ID by inheriting the missing middle component and revision from the covered ID on the right side before opening the corresponding declaration.
 
 Covers:
 - `scn~show-specification-item-in-go-to-symbol~1`
@@ -269,7 +269,7 @@ Needs: impl
 ### Specification Item Completion
 `dsn~specification-item-completion~1`
 
-The plugin provides a specification-item completion component that activates IntelliJ basic completion for supported OFT reference authoring contexts, reads declared specification item IDs from the project-local declaration index, and presents those IDs in a deterministic order based on full-ID prefix, name-prefix, name-substring, and artifact-type prefix matches. Supported contexts include OFT item references under `Covers:` in supported specification documents, completion requests started from an active live-template placeholder when the placeholder expands inside a `Covers:` entry, and the target side of likely OFT coverage tags in source-code comments for the default file extensions supported by the upstream OpenFastTrace Tag Importer after a left-hand artifact type and arrow.
+The plugin provides a specification-item completion component that activates IntelliJ basic completion for supported OFT reference authoring contexts, reads declared specification item IDs from the project-local declaration index, and presents those IDs in a deterministic order based on full-ID prefix, middle-component prefix, middle-component substring, and artifact-type prefix matches. Supported contexts include OFT item references under `Covers:` in supported specification documents, completion requests started from an active live-template placeholder when the placeholder expands inside a `Covers:` entry, and the target side of likely OFT coverage tags in source-code comments for the default file extensions supported by the upstream OpenFastTrace Tag Importer after a left-hand artifact type and arrow.
 
 Covers:
 - `scn~complete-specification-item-id-in-covers-section~1`
@@ -382,7 +382,7 @@ Needs: impl, itest
 ### Trace Test Runner Presentation
 `dsn~trace-test-runner-presentation~1`
 
-The plugin provides a trace test-runner presentation component that maps the structured OpenFastTrace trace result to IntelliJ SM test runner nodes. It creates project-local source-file suites, sorted specification-item tests, and incoming or outgoing trace-link sub-tests; derives compact title-aware labels, Unicode direction markers, pass/fail status, status roll-up, and item/link details from the OpenFastTrace trace status; and connects source-file, item, and link node navigation to the existing OpenFastTrace trace navigation support.
+The plugin provides a trace test-runner presentation component that maps the structured OpenFastTrace trace result to IntelliJ SM test runner nodes. It creates project-local source-file suites, sorted specification-item tests, and incoming or outgoing trace-link sub-tests; derives compact title-aware labels, Unicode direction markers, transitive-defect markers, pass/fail status, status roll-up, and item/link details from the OpenFastTrace trace status; and connects source-file, item, and link node navigation to the existing OpenFastTrace trace navigation support.
 
 Covers:
 - `scn~show-trace-source-files-as-test-runner-suites~1`
@@ -392,6 +392,7 @@ Covers:
 - `scn~sort-specification-items-in-test-runner-ui~1`
 - `scn~show-trace-links-as-test-runner-sub-tests~1`
 - `scn~show-specification-item-status-in-test-runner-ui~2`
+- `scn~mark-transitive-defects-in-test-runner~1`
 - `scn~show-trace-link-status-in-test-runner-ui~2`
 - `scn~show-trace-link-direction-in-test-runner-ui~1`
 - `scn~show-unicode-trace-link-direction-in-test-runner-ui~1`

doc/design/runtime_view.md

@@ -205,7 +205,7 @@ Needs: impl, itest
 
 **Given** a supported source file contains an OFT coverage tag whose left side is shortened and the corresponding covering specification item is declared in the project
 **When** a user invokes `Go To Declaration` on the left side of the coverage tag
-**Then** the navigation component resolves the effective covering item ID by copying the missing name and revision parts from the covered ID on the right side and opens the specification document at the declaration anchor of that covering item.
+**Then** the navigation component resolves the effective covering item ID by copying the missing middle component and revision from the covered ID on the right side and opens the specification document at the declaration anchor of that covering item.
 
 Covers:
 - `scn~open-specification-item-from-coverage-tag-left-side~1`
@@ -232,7 +232,7 @@ Needs: impl, itest
 **Given** a supported specification document contains a `Covers:` entry and the opened project already indexes declared OpenFastTrace specification items
 **When** a user invokes IntelliJ basic completion while editing an OFT item ID in that `Covers:` entry
 **Then** the completion component confirms that the caret is inside a `Covers:` reference, loads declared specification item IDs from the declaration index
-**And** ranks them by full-ID prefix, name-prefix, name-substring, and artifact-type prefix matches
+**And** ranks them by full-ID prefix, middle-component prefix, middle-component substring, and artifact-type prefix matches
 **And** shows the ordered suggestions in the standard IDE completion popup.
 
 Covers:
@@ -258,7 +258,7 @@ Needs: impl, itest
 
 **Given** a source, configuration, or markup file with a default extension supported by the upstream OpenFastTrace Tag Importer contains a comment with an OFT coverage-tag candidate whose left-hand side contains an artifact type and whose right-hand side contains the caret after `->`
 **When** a user invokes IntelliJ basic completion on the right-hand side
-**Then** the completion component confirms the supported file and comment context, extracts the target-side prefix under the caret, loads declared specification item IDs from the declaration index, ranks them by full-ID prefix, name-prefix, name-substring, and artifact-type prefix matches, and shows the ordered suggestions in the standard IDE completion popup.
+**Then** the completion component confirms the supported file and comment context, extracts the target-side prefix under the caret, loads declared specification item IDs from the declaration index, ranks them by full-ID prefix, middle-component prefix, middle-component substring, and artifact-type prefix matches, and shows the ordered suggestions in the standard IDE completion popup.
 
 Covers:
 - `scn~complete-specification-item-id-in-coverage-tag-target~1`
@@ -346,7 +346,7 @@ Needs: impl, itest
 
 **Given** the bundled OpenFastTrace live-template group is available in a supported editing context
 **When** a user expands the `scn` live template
-**Then** IntelliJ inserts the scenario template text from the bundled plugin resource and lets the user tab through the placeholders for the title, item name, `Given`, `When`, `Then`, and covered requirement.
+**Then** IntelliJ inserts the scenario template text from the bundled plugin resource and lets the user tab through the placeholders for the title, item ID, `Given`, `When`, `Then`, and covered requirement.
 
 Covers:
 - `scn~insert-oft-scenario-live-template~1`
@@ -575,7 +575,7 @@ Needs: impl, itest
 
 **Given** the trace test-runner presentation maps traced specification items for one source-file suite
 **When** it creates the specification-item test nodes
-**Then** it orders them by artifact type, the specification item ID name part, and revision number.
+**Then** it orders them by artifact type, the middle component of the specification item ID, and revision number.
 
 Covers:
 - `scn~sort-specification-items-in-test-runner-ui~1`
@@ -606,6 +606,18 @@ Covers:
 
 Needs: impl, itest
 
+No### Mark Transitive Defects in Test Runner UI
+`dsn~mark-transitive-defects-in-test-runner~1`
+
+**Given** the trace test-runner presentation creates a specification-item test node for a defective item that is identified as a transitive defect
+**When** it derives the node name from the OpenFastTrace trace result
+**Then** it prefixes the visible node name with `↳` so transitive defects are visually distinct in the tree.
+
+Covers:
+- `scn~mark-transitive-defects-in-test-runner~1`
+
+Needs: impl, itest
+
 ### Show Trace Link Status in Test Runner UI
 `dsn~show-trace-link-status-in-test-runner-ui~2`
 

doc/design/solution_strategy.md

@@ -30,7 +30,7 @@ This strategy reduces custom code, lowers maintenance effort, and improves cross
 
 The index distinguishes rigorously between OpenFastTrace declarations and OpenFastTrace coverage occurrences. That distinction is the foundation for correct IDE navigation.
 
-An OpenFastTrace specification item is declared only in a specification document such as Markdown or reStructuredText when the document defines the item itself. The declaration is the item header line that contains the full OpenFastTrace item ID, for example `req~user_login~1`. In Markdown, OFT permits two declaration forms for that line: the plain full ID and the same full ID enclosed in single backticks. Both forms declare the same specification item and must therefore produce the same canonical declaration identity for indexing and navigation. This full ID is the canonical identity of the item because it combines artifact type, name, and revision into the stable project-wide key. The precise location of the declaration is the text range of that ID in the specification item header. In OFT terms, this is the item's visible sub-title. In IDE terms, this is the declaration site and primary navigation target.
+An OpenFastTrace specification item is declared only in a specification document such as Markdown or reStructuredText when the document defines the item itself. The declaration is the item header line that contains the full OpenFastTrace item ID, for example `req~user_login~1`. In Markdown, OFT permits two declaration forms for that line: the plain full ID and the same full ID enclosed in single backticks. Both forms declare the same specification item and must therefore produce the same canonical declaration identity for indexing and navigation. This full ID is the canonical identity of the item because it combines artifact type, the middle component of the ID, and revision into the stable project-wide key. The precise location of the declaration is the text range of that ID in the specification item header. In OFT terms, this is the item's visible sub-title. In IDE terms, this is the declaration site and primary navigation target.
 
 The remainder of the specification item body does not declare the item again. In particular, entries under `Covers:` are not declarations. They are coverage occurrences that point to other declared specification items. The same is true for OFT coverage tags in source files. These locations provide coverage in the OpenFastTrace domain model, but from the JetBrains IDE point of view they are usages or references of an already declared item.
 
@@ -39,17 +39,17 @@ This terminology matters because the IntelliJ Platform separates declarations fr
 The OFT to JetBrains mapping is therefore as follows:
 
 - An OFT specification item identified by its full ID is the semantic project entity that users search and navigate to. Conceptually this is the symbol.
-- The occurrence of that full ID in the header of a specification item in `.md`, `.markdown`, or `.rst` is the declaration. In Markdown, both the plain form and the single-backtick form are declaration forms of the same item. In a PSI-first implementation this declaration is represented by a PSI element that carries the item's canonical name and can act as a `NavigationItem`.
+- The occurrence of that full ID in the header of a specification item in `.md`, `.markdown`, or `.rst` is the declaration. In Markdown, both the plain form and the single-backtick form are declaration forms of the same item. In a PSI-first implementation this declaration is represented by a PSI element that carries the item's canonical identifier and can act as a `NavigationItem`.
 - The text range of the full ID inside that header is the declaration anchor. That is the range that `Go To` and search results should open.
 - An occurrence of an OFT item ID under `Covers:` in a specification document is a reference from one item to another declared item.
 - An occurrence of an OFT item ID inside an OFT coverage tag in source code is also a reference from that source location to a declared item.
 - A `Go to Symbol` result is produced from indexed declarations only. Coverage occurrences are not separate symbol results.
 
-This mapping also clarifies what the index stores. The symbol-facing index stores declarations keyed by the canonical full OFT item ID. Additional lookup keys such as the name part may be stored as aliases for search convenience, but they do not replace the canonical identity. The artifact type prefix such as `req`, `dsn`, or `impl` is part of that identity and may additionally be surfaced as presentation metadata, grouping information, or a type label in result lists.
+This mapping also clarifies what the index stores. The symbol-facing index stores declarations keyed by the canonical full OFT item ID. Additional lookup keys such as the middle component of the ID may be stored as aliases for search convenience, but they do not replace the canonical identity. The artifact type prefix such as `req`, `dsn`, or `impl` is part of that identity and may additionally be surfaced as presentation metadata, grouping information, or a type label in result lists.
 
-For IntelliJ's search and navigation facilities, the declaration index is the source of truth for `Go to Symbol` and `Search Everywhere`. JetBrains documents [Go to Symbol](https://plugins.jetbrains.com/docs/intellij/go-to-class-and-go-to-symbol.html) as a contributor that feeds the IDE with names and matching `NavigationItem` instances, typically PSI elements. The plugin contributes declaration elements, not synthetic wrappers around arbitrary text matches and not coverage occurrences. This keeps symbol search aligned with the IDE expectation that a search result names something that is actually declared somewhere in the project.
+For IntelliJ's search and navigation facilities, the declaration index is the source of truth for `Go to Symbol` and `Search Everywhere`. JetBrains documents [Go to Symbol](https://plugins.jetbrains.com/docs/intellij/go-to-class-and-go-to-symbol.html) as a contributor that feeds the IDE with IDs and matching `NavigationItem` instances, typically PSI elements. The plugin contributes declaration elements, not synthetic wrappers around arbitrary text matches and not coverage occurrences. This keeps symbol search aligned with the IDE expectation that a search result names something that is actually declared somewhere in the project.
 
-Coverage locations are still first-class data, but they belong in reference resolution and usage-style navigation. They are the places where the IDE should resolve from a usage to a declaration, and they are also the basis for `Go To Implementations` on a declared specification item. The same declaration index also feeds completion in `Covers:` sections and on the target side of likely source-code coverage tags, where the plugin ranks declared IDs by full-ID prefix, name-prefix, name-substring, and artifact-type prefix matches in that order.
+Coverage locations are still first-class data, but they belong in reference resolution and usage-style navigation. They are the places where the IDE should resolve from a usage to a declaration, and they are also the basis for `Go To Implementations` on a declared specification item. The same declaration index also feeds completion in `Covers:` sections and on the target side of likely source-code coverage tags, where the plugin ranks declared IDs by full-ID prefix, middle-component prefix, middle-component substring, and artifact-type prefix matches in that order.
 
 ## Phased OFT Integration