Fix category-file locations and markdown headers

.github/standards/design-documentation.md

@@ -35,16 +35,21 @@ design to implementation:
 
 ```text
 docs/design/
-├── introduction.md              # Design overview with software structure
-└── {system-name}/               # System-level design folder (one per system)
-    ├── {system-name}.md         # System-level design documentation
-    ├── {subsystem-name}/        # Subsystem (kebab-case); may nest recursively
-    │   ├── {subsystem-name}.md  # Subsystem overview and design
-    │   ├── {child-subsystem}/   # Child subsystem (same structure as parent)
-    │   └── {unit-name}.md       # Unit-level design documents
-    └── {unit-name}.md           # Top-level unit design documents (if not in subsystem)
+├── introduction.md              # Document overview — heading depth #
+├── {system-name}.md             # System-level design — heading depth #
+└── {system-name}/               # System folder (one per system)
+    ├── {subsystem-name}.md      # Subsystem overview — heading depth ##
+    ├── {subsystem-name}/        # Subsystem folder (kebab-case); may nest recursively
+    │   ├── {child-subsystem}.md # Child subsystem overview — heading depth ###
+    │   ├── {child-subsystem}/   # Child subsystem folder (same structure as parent)
+    │   └── {unit-name}.md       # Unit design — heading depth ###
+    └── {unit-name}.md           # System-level unit design — heading depth ##
 ```
 
+Each scope's overview file lives in its **parent** folder, not inside the scope's own
+subfolder — this aligns heading depth with folder depth so the compiled PDF has a
+meaningful multi-level outline (see Heading Depth Rule in `technical-documentation.md`).
+
 ## introduction.md (MANDATORY)
 
 The `introduction.md` file serves as the design entry point and MUST include
@@ -127,20 +132,21 @@ Example format:
 Each software item in the structure above has corresponding artifacts in
 parallel directory trees:
 
-- Requirements: `docs/reqstream/{system}/.../{item}.yaml` (kebab-case)
-- Design docs: `docs/design/{system}/.../{item}.md` (kebab-case)
-- Verification design: `docs/verification/{system}/.../{item}.md` (kebab-case)
-- Source code: `src/{System}/.../{Item}.{ext}` (cased per language - see `software-items.md`)
-- Tests: `test/{System}.Tests/.../{Item}Tests.{ext}` (cased per language - see `software-items.md`)
-- Review-sets: defined in `.reviewmark.yaml`
+- Requirements: `docs/reqstream/{system-name}.yaml`, `docs/reqstream/{system-name}/.../{item}.yaml`
+- Design docs:  `docs/design/{system-name}.md`, `docs/design/{system-name}/.../{item}.md`
+- Verification: `docs/verification/{system-name}.md`, `docs/verification/{system-name}/.../{item}.md`
+- Source code:  `src/{SystemName}/.../{Item}.{ext}` (cased per language - see `software-items.md`)
+- Tests:        `test/{SystemName}.Tests/.../{Item}Tests.{ext}` (cased per language)
+- Review-sets:  defined in `.reviewmark.yaml`
 ```
 
 ## System Design Documentation (MANDATORY)
 
 For each system identified in the repository:
 
-- Create a kebab-case folder matching the system name
-- Include `{system-name}.md` with system-level design documentation such as:
+- Create `{system-name}.md` directly under `docs/design/` (heading depth `#`)
+- Create a kebab-case folder `{system-name}/` to hold its subsystems and units
+- `{system-name}.md` must cover:
   - System architecture and major components
   - External interfaces and dependencies
   - Data flow and control flow
@@ -151,16 +157,20 @@ For each system identified in the repository:
 
 For each subsystem identified in the software structure:
 
-- Create a kebab-case folder matching the subsystem name (enables automated tooling)
-- Include `{subsystem-name}.md` with subsystem overview and design
-- Include unit design documents for ALL units within the subsystem
+- Place `{subsystem-name}.md` inside the **parent** folder (the system folder, or parent
+  subsystem folder) — not inside its own subfolder
+- Create a kebab-case folder `{subsystem-name}/` to hold its child units and subsystems
+- `{subsystem-name}.md` must cover subsystem overview and design
 
 For every unit identified in the software structure:
 
+- Place `{unit-name}.md` inside its parent scope's folder (system or subsystem folder)
 - Document data models, algorithms, and key methods
 - Describe interactions with other units
 - Include sufficient detail for formal code review
-- Place in appropriate subsystem folder or at design root level
+
+Follow the Heading Depth Rule from `technical-documentation.md` — a file's top-level
+heading depth equals its folder depth under `docs/design/`.
 
 # Software Items Integration (CRITICAL)
 
@@ -191,9 +201,11 @@ Before submitting design documentation, verify:
 - [ ] `introduction.md` includes both Software Structure and Folder Layout sections
 - [ ] Software structure correctly categorizes items as System/Subsystem/Unit per `software-items.md`
 - [ ] Folder layout mirrors software structure organization
+- [ ] Files organized under `docs/design/` following the folder structure pattern above
+- [ ] Each file's top-level heading depth matches its folder depth per the Heading Depth Rule
 - [ ] Design documents provide sufficient detail for code review
 - [ ] System documentation provides comprehensive system-level design
-- [ ] Subsystem documentation folders use kebab-case names while mirroring source subsystem names and structure
+- [ ] All documentation folders use kebab-case names mirroring source code structure
 - [ ] All documents follow technical documentation formatting standards
 - [ ] Content is current with implementation and requirements
 - [ ] Documents are integrated into ReviewMark review-sets for formal review

.github/standards/reqstream-usage.md

@@ -18,20 +18,25 @@ because ReqStream discovers files via the includes chain in `requirements.yaml`
 and organizes report output by this hierarchy:
 
 ```text
-requirements.yaml                   # Root file (includes only)
+requirements.yaml                    # Root file (includes only)
 docs/reqstream/
-├── {system-name}/                  # System-level requirements folder (one per system)
-│   ├── {system-name}.yaml          # System-level requirements
+├── {system-name}.yaml               # System-level requirements
+├── {system-name}/                   # System folder (one per system)
 │   ├── platform-requirements.yaml  # Platform support requirements
-│   ├── {subsystem-name}/           # Subsystem (kebab-case); may nest recursively
-│   │   ├── {subsystem-name}.yaml   # Requirements for this subsystem
-│   │   ├── {child-subsystem}/      # Child subsystem (same structure as parent)
-│   │   └── {unit-name}.yaml        # Requirements for units within this subsystem
-│   └── {unit-name}.yaml            # Requirements for top-level units (outside subsystems)
-└── ots/                            # OTS items appear as a distinct section in reports
-    └── {ots-name}.yaml             # Requirements for OTS components
+│   ├── {subsystem-name}.yaml        # Subsystem requirements
+│   ├── {subsystem-name}/            # Subsystem folder (kebab-case); may nest recursively
+│   │   ├── {child-subsystem}.yaml   # Child subsystem requirements
+│   │   ├── {child-subsystem}/       # Child subsystem folder
+│   │   └── {unit-name}.yaml         # Unit requirements
+│   └── {unit-name}.yaml             # System-level unit requirements
+└── ots/                             # OTS items appear as a distinct section in reports
+    └── {ots-name}.yaml              # Requirements for OTS components
 ```
 
+This mirrors the `docs/design/` and `docs/verification/` folder structures exactly —
+each item's requirements, design, and verification files share the same relative path
+under their respective roots, making artifact locations deterministic.
+
 # Requirements File Format
 
 ```yaml
@@ -124,8 +129,8 @@ Before submitting requirements, verify:
 - [ ] Every requirement links to at least one passing test
 - [ ] Platform-specific requirements use source filters (`platform@TestName`)
 - [ ] Comprehensive justification explains business/regulatory need
-- [ ] Files organized under `docs/reqstream/` following folder structure patterns
-- [ ] Subsystem folders use kebab-case naming matching source code
+- [ ] Files organized under `docs/reqstream/` following the folder structure pattern above
+- [ ] All documentation folders use kebab-case names matching source code structure
 - [ ] OTS requirements placed in `ots/` subfolder
 - [ ] Valid YAML syntax passes yamllint validation
 - [ ] Test result formats compatible (TRX, JUnit XML)

.github/standards/reviewmark-usage.md

@@ -61,6 +61,17 @@ needs-review:
 # Source of review evidence
 evidence-source:
   type: none
+
+# Review-sets (each focuses on a single compliance question)
+reviews:
+  - id: Purpose
+    title: Review of user-facing capabilities and system promises
+    paths:
+      - "README.md"
+      - "docs/user_guide/**/*.md"
+      - "docs/reqstream/{system-name}/{system-name}.yaml"
+      - "docs/design/introduction.md"
+      - "docs/design/{system-name}/{system-name}.md"
 ```
 
 # Review-Set Design Principles

.github/standards/technical-documentation.md

@@ -84,6 +84,23 @@ elsewhere causes duplicate sections in the compiled PDF.
 List documents in logical reading order in Pandoc configuration because
 readers need coherent information flow from general to specific topics.
 
+## Heading Depth Rule (MANDATORY)
+
+A file's top-level heading depth must equal its folder depth under the document
+collection root — this ensures Pandoc can concatenate all files in `definition.yaml`
+order and produce a coherent outline with no heading-shift configuration:
+
+| Folder depth | Top heading |
+| --- | --- |
+| 0 — collection root | `#` |
+| 1 — one subfolder deep | `##` |
+| 2 — two subfolders deep | `###` |
+| N — N subfolders deep | `#` × (N+1) |
+
+Internal sections use the next heading level down (e.g. a `##` file uses `###`
+for *Overview*, *Interfaces*, etc.). Deeply nested files have fewer heading levels
+available — keep internal structure flat to avoid excessive nesting.
+
 # Writing Guidelines
 
 Write technical documentation for clarity and compliance verification:

.github/standards/verification-documentation.md

@@ -23,18 +23,24 @@ Organize under `docs/verification/` mirroring the software item hierarchy:
 
 ```text
 docs/verification/
-├── introduction.md              # Verification overview
-├── {system-name}/               # System-level verification folder (one per system)
-│   ├── {system-name}.md         # System-level verification design
-│   ├── {subsystem-name}/        # Subsystem (kebab-case); may nest recursively
-│   │   ├── {subsystem-name}.md  # Subsystem verification design
-│   │   ├── {child-subsystem}/   # Child subsystem (same structure as parent)
-│   │   └── {unit-name}.md       # Unit-level verification design documents
-│   └── {unit-name}.md           # Top-level unit verification documents (if not in subsystem)
-└── ots/                         # OTS items (one verification file per OTS item)
-    └── {ots-name}.md            # Verification evidence for each OTS item
+├── introduction.md              # Document overview — heading depth #
+├── {system-name}.md             # System-level verification — heading depth #
+└── {system-name}/               # System folder (one per system)
+    ├── {subsystem-name}.md      # Subsystem verification — heading depth ##
+    ├── {subsystem-name}/        # Subsystem folder (kebab-case); may nest recursively
+    │   ├── {child-subsystem}.md # Child subsystem verification — heading depth ###
+    │   ├── {child-subsystem}/   # Child subsystem folder (same structure as parent)
+    │   └── {unit-name}.md       # Unit verification — heading depth ###
+    ├── {unit-name}.md           # System-level unit verification — heading depth ##
+    └── ots/                     # OTS items (one verification file per OTS item)
+        └── {ots-name}.md        # OTS item verification evidence
 ```
 
+Each scope's overview file lives in its **parent** folder, not inside the scope's own
+subfolder — this keeps artifact locations consistent with design and requirements trees
+so any item's files are deterministically locatable, and aligns heading depth with folder
+depth for correct PDF structure (see Heading Depth Rule in `technical-documentation.md`).
+
 ## introduction.md (MANDATORY)
 
 Follow the standard `introduction.md` format from `technical-documentation.md`. Scope
@@ -45,15 +51,15 @@ artifact to all related files:
 
 ```text
 In-house items have parallel artifacts in:
-- Requirements: `docs/reqstream/{system}/.../{item}.yaml` (kebab-case)
-- Design: `docs/design/{system}/.../{item}.md` (kebab-case)
-- Verification: `docs/verification/{system}/.../{item}.md` (kebab-case)
-- Source: `src/{System}/.../{Item}.{ext}` (cased per language)
-- Tests: `test/{System}.Tests/.../{Item}Tests.{ext}` (cased per language)
+- Requirements: `docs/reqstream/{system-name}.yaml`, `docs/reqstream/{system-name}/.../{item}.yaml`
+- Design:        `docs/design/{system-name}.md`, `docs/design/{system-name}/.../{item}.md`
+- Verification:  `docs/verification/{system-name}.md`, `docs/verification/{system-name}/.../{item}.md`
+- Source:        `src/{SystemName}/.../{Item}.{ext}` (cased per language)
+- Tests:         `test/{SystemName}.Tests/.../{Item}Tests.{ext}` (cased per language)
 
 OTS items have parallel artifacts in:
-- Requirements: `docs/reqstream/ots/{ots-name}.yaml` (kebab-case)
-- Verification: `docs/verification/ots/{ots-name}.md` (kebab-case)
+- Requirements: `docs/reqstream/ots/{ots-name}.yaml`
+- Verification: `docs/verification/ots/{ots-name}.md`
 - Tests: `test/{OtsName}.Tests/...` (cased per language, if required)
 
 Review-sets: defined in `.reviewmark.yaml`
@@ -64,7 +70,8 @@ a `## References` section in `introduction.md` only - do not add one to any othe
 
 ## System Verification Design (MANDATORY)
 
-For each system, create a kebab-case folder and `{system-name}.md` covering:
+For each system, create `{system-name}.md` at `docs/verification/` root and a
+`{system-name}/` folder for subsystems. Cover:
 
 - System verification strategy and overall test approach
 - Test environments and configuration required
@@ -75,7 +82,8 @@ For each system, create a kebab-case folder and `{system-name}.md` covering:
 
 ## Subsystem Verification Design (MANDATORY)
 
-For each subsystem, create a kebab-case folder and `{subsystem-name}.md` covering:
+For each subsystem, place `{subsystem-name}.md` in the parent (system or subsystem)
+folder and create a `{subsystem-name}/` folder for its units. Cover:
 
 - Subsystem verification strategy and integration test approach
 - Dependencies that must be mocked or stubbed at the subsystem boundary
@@ -84,7 +92,7 @@ For each subsystem, create a kebab-case folder and `{subsystem-name}.md` coverin
 
 ## Unit Verification Design (MANDATORY)
 
-For each unit, create `{unit-name}.md` covering:
+Place `{unit-name}.md` in the parent (system or subsystem) folder. Cover:
 
 - Verification approach for each unit requirement
 - Named test scenarios including boundary conditions, error paths, and normal-operation cases
@@ -121,7 +129,9 @@ Before submitting verification documentation, verify:
 - [ ] System verification documents cover end-to-end and integration scenarios
 - [ ] Subsystem verification documents identify mocked boundaries and integration scenarios
 - [ ] Unit verification documents identify individual scenarios including boundary and error paths
-- [ ] Subsystem documentation folders use kebab-case names mirroring the source subsystem structure
+- [ ] Files organized under `docs/verification/` following the folder structure pattern above
+- [ ] Each file's top-level heading depth matches its folder depth per the Heading Depth Rule
+- [ ] All documentation folders use kebab-case names mirroring source code structure
 - [ ] All documents follow technical documentation formatting standards
 - [ ] Content is current with requirements and test implementation
 - [ ] Every OTS item has `docs/verification/ots/{ots-name}.md` with requirement coverage

docs/design/build-mark/build-notes/build-notes.md → docs/design/build-mark/build-notes.md

@@ -1,6 +1,6 @@
-# BuildNotes Subsystem
+## BuildNotes Subsystem
 
-## Overview
+### Overview
 
 The BuildNotes subsystem holds the output data model shared by all connectors and
 by `Program`. It defines the records that represent a build's version tags,
@@ -10,15 +10,15 @@ a markdown report.
 All connectors produce a `BuildInformation` record from these types, and `Program`
 calls `BuildInformation.ToMarkdown` to write the final report file.
 
-## Units
+### Units
 
 | Unit               | File                             | Responsibility                                   |
 |--------------------|----------------------------------|--------------------------------------------------|
 | `BuildInformation` | `BuildNotes/BuildInformation.cs` | Top-level build data model and markdown renderer |
 | `ItemInfo`         | `BuildNotes/ItemInfo.cs`         | Single issue or pull request in the report       |
 | `WebLink`          | `BuildNotes/WebLink.cs`          | Hyperlink used for the full-changelog entry      |
 
-## Interactions
+### Interactions
 
 | Unit / Subsystem    | Role                                                               |
 |---------------------|--------------------------------------------------------------------|

docs/design/build-mark/build-notes/build-information.md

@@ -1,12 +1,12 @@
-# BuildInformation
+### BuildInformation
 
-## Overview
+#### Overview
 
 `BuildInformation` is a record in the BuildNotes subsystem that holds all data
 needed to produce one markdown build-notes report. It is assembled by connectors
 and passed to `Program`, which calls `ToMarkdown` to render the final file.
 
-## Data Model
+#### Data Model
 
 ```csharp
 public record BuildInformation(
@@ -30,9 +30,9 @@ public record BuildInformation(
   optional ordered list of custom report sections populated by `RepoConnectorBase.ApplyRules`
   when routing rules are configured; `null` when no rules are active
 
-## Methods
+#### Methods
 
-### `ToMarkdown(headingDepth, includeKnownIssues) → string`
+##### `ToMarkdown(headingDepth, includeKnownIssues) → string`
 
 Renders the build information as a markdown string. The `headingDepth` parameter
 controls the top-level heading depth (default `1`), allowing the report to be
@@ -57,7 +57,7 @@ The rendered output contains the following sections:
 3. **Full Changelog** *(optional)* - hyperlink from `CompleteChangelogLink`, emitted
    only when the link is non-null.
 
-## Interactions
+#### Interactions
 
 | Unit / Subsystem   | Role                                                              |
 | :----------------- | :---------------------------------------------------------------- |

docs/design/build-mark/build-notes/item-info.md

@@ -1,12 +1,12 @@
-# ItemInfo
+### ItemInfo
 
-## Overview
+#### Overview
 
 `ItemInfo` is a record in the BuildNotes subsystem that represents a single issue
 or pull request entry in the build report. It is produced by connectors and stored
 in the `Changes`, `Bugs`, and `KnownIssues` lists of `BuildInformation`.
 
-## Data Model
+#### Data Model
 
 ```csharp
 public record ItemInfo(
@@ -27,7 +27,7 @@ public record ItemInfo(
 | `Index`            | `int`                 | Numeric issue/PR number for deterministic sorting          |
 | `AffectedVersions` | `VersionIntervalSet?` | Interval set from the `affected-versions` field, or `null` |
 
-## Interactions
+#### Interactions
 
 | Unit / Subsystem    | Role                                                        |
 |---------------------|-------------------------------------------------------------|