Changes before error encountered

Agent-Logs-Url: https://github.com/demaconsulting/BuildMark/sessions/a338e6d6-893c-4cbd-a64b-01abce243e9d

Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

.cspell.yaml

@@ -18,7 +18,7 @@ words:
   - Blockquotes
   - buildmark
   - BuildMark
-  - buildnotes
+  - build_notes
   - camelcase
   - Checkmarx
   - codeql
@@ -59,6 +59,11 @@ words:
   - Qube
   - reqstream
   - ReqStream
+  - code_quality
+  - code_review_plan
+  - code_review_report
+  - requirements_doc
+  - requirements_report
   - reviewmark
   - ReviewMark
   - Sarif
@@ -75,7 +80,7 @@ words:
   - spdx
   - streetsidesoftware
   - TMPL
-  - tracematrix
+  - trace_matrix
   - triaging
   - Trivy
   - trx

.github/pull_request_template.md

@@ -43,9 +43,7 @@ Before submitting this pull request, ensure you have completed the following:
 
 Please run the following checks before submitting:
 
-- [ ] **Spell checker passes**: `cspell "**/*.{md,cs}"`
-- [ ] **Markdown linter passes**: `markdownlint "**/*.md"`
-- [ ] **YAML linter passes**: `yamllint '**/*.{yml,yaml}'`
+- [ ] **All linters pass**: `./lint.sh` (Unix/macOS) or `cmd /c lint.bat` / `./lint.bat` (Windows)
 
 ### Testing
 

.github/standards/technical-documentation.md

@@ -114,9 +114,9 @@ for consistency and professional presentation:
 **NEVER modify auto-generated markdown files** because changes will be
 overwritten and break compliance automation:
 
-- **Read-Only Files**: Generated reports under `docs/requirements/`,
-  `docs/justifications/`, `docs/tracematrix/`, `docs/quality/`, and
-  `docs/buildnotes/` are regenerated on every build
+- **Read-Only Files**: Generated reports under `docs/requirements_doc/`,
+  `docs/requirements_report/`, `docs/code_quality/`, and
+  `docs/build_notes/` are regenerated on every build
 - **Source Modification**: Update source files (requirements YAML, code
   comments) instead of generated output
 - **Tool Integration**: Generated content integrates with CI/CD pipelines and

.github/workflows/build.yaml

@@ -495,24 +495,24 @@ jobs:
           dotnet reqstream
           --requirements requirements.yaml
           --tests "artifacts/**/*.trx"
-          --report docs/requirements/requirements.md
-          --matrix docs/tracematrix/tracematrix.md
-          --justifications docs/justifications/justifications.md
+          --report docs/requirements_doc/requirements.md
+          --matrix docs/requirements_report/trace_matrix.md
+          --justifications docs/requirements_doc/justifications.md
           --enforce
 
       - name: Generate CodeQL Quality Report with SarifMark
         run: >
           dotnet sarifmark
           --sarif artifacts/csharp.sarif
-          --report docs/quality/codeql-quality.md
+          --report docs/code_quality/codeql-quality.md
           --heading "BuildMark CodeQL Analysis"
           --report-depth 1
 
       - name: Display CodeQL Quality Report
         shell: bash
         run: |
           echo "=== CodeQL Quality Report ==="
-          cat docs/quality/codeql-quality.md
+          cat docs/code_quality/codeql-quality.md
 
       - name: Generate Code Quality Report with SonarMark
         shell: bash
@@ -524,14 +524,14 @@ jobs:
           --project-key demaconsulting_BuildMark
           --branch ${{ github.head_ref || github.ref_name }}
           --token "$SONAR_TOKEN"
-          --report docs/quality/sonar-quality.md
+          --report docs/code_quality/sonar-quality.md
           --report-depth 1
 
       - name: Display SonarCloud Quality Report
         shell: bash
         run: |
           echo "=== SonarCloud Quality Report ==="
-          cat docs/quality/sonar-quality.md
+          cat docs/code_quality/sonar-quality.md
 
       - name: Generate Build Notes with BuildMark
         env:
@@ -540,15 +540,15 @@ jobs:
         run: >
           buildmark
           --build-version ${{ inputs.version }}
-          --report docs/buildnotes.md
+          --report docs/build_notes.md
           --report-depth 1
 
       - name: Publish Tool Versions
         shell: bash
         run: |
           echo "Publishing tool versions..."
           dotnet versionmark --publish \
-            --report docs/buildnotes/versions.md \
+            --report docs/build_notes/versions.md \
             --report-depth 1 \
             -- "artifacts/**/versionmark-*.json"
           echo "✓ Tool versions published"
@@ -557,13 +557,13 @@ jobs:
         shell: bash
         run: |
           echo "=== Tool Versions Report ==="
-          cat docs/buildnotes/versions.md
+          cat docs/build_notes/versions.md
 
       - name: Display Build Notes Report
         shell: bash
         run: |
           echo "=== Build Notes Report ==="
-          cat docs/buildnotes.md
+          cat docs/build_notes.md
 
       # === GENERATE HTML DOCUMENTS WITH PANDOC ===
       # This section converts markdown documents to HTML using Pandoc.
@@ -573,11 +573,11 @@ jobs:
         shell: bash
         run: >
           dotnet pandoc
-          --defaults docs/buildnotes/definition.yaml
+          --defaults docs/build_notes/definition.yaml
           --filter node_modules/.bin/mermaid-filter.cmd
           --metadata version="${{ inputs.version }}"
           --metadata date="$(date +'%Y-%m-%d')"
-          --output docs/buildnotes/buildnotes.html
+          --output docs/build_notes/buildnotes.html
 
       - name: Generate User Guide HTML with Pandoc
         shell: bash
@@ -593,41 +593,31 @@ jobs:
         shell: bash
         run: >
           dotnet pandoc
-          --defaults docs/requirements/definition.yaml
+          --defaults docs/requirements_doc/definition.yaml
           --filter node_modules/.bin/mermaid-filter.cmd
           --metadata version="${{ inputs.version }}"
           --metadata date="$(date +'%Y-%m-%d')"
-          --output docs/requirements/requirements.html
+          --output docs/requirements_doc/requirements.html
 
       - name: Generate Trace Matrix HTML with Pandoc
         shell: bash
         run: >
           dotnet pandoc
-          --defaults docs/tracematrix/definition.yaml
+          --defaults docs/requirements_report/definition.yaml
           --filter node_modules/.bin/mermaid-filter.cmd
           --metadata version="${{ inputs.version }}"
           --metadata date="$(date +'%Y-%m-%d')"
-          --output docs/tracematrix/tracematrix.html
-
-      - name: Generate Requirements Justifications HTML with Pandoc
-        shell: bash
-        run: >
-          dotnet pandoc
-          --defaults docs/justifications/definition.yaml
-          --filter node_modules/.bin/mermaid-filter.cmd
-          --metadata version="${{ inputs.version }}"
-          --metadata date="$(date +'%Y-%m-%d')"
-          --output docs/justifications/justifications.html
+          --output docs/requirements_report/trace_matrix.html
 
       - name: Generate Code Quality HTML with Pandoc
         shell: bash
         run: >
           dotnet pandoc
-          --defaults docs/quality/definition.yaml
+          --defaults docs/code_quality/definition.yaml
           --filter node_modules/.bin/mermaid-filter.cmd
           --metadata version="${{ inputs.version }}"
           --metadata date="$(date +'%Y-%m-%d')"
-          --output docs/quality/quality.html
+          --output docs/code_quality/quality.html
 
       # === GENERATE PDF DOCUMENTS WITH WEASYPRINT ===
       # This section converts HTML documents to PDF using Weasyprint.
@@ -637,7 +627,7 @@ jobs:
         run: >
           dotnet weasyprint
           --pdf-variant pdf/a-3u
-          docs/buildnotes/buildnotes.html
+          docs/build_notes/buildnotes.html
           "docs/BuildMark Build Notes.pdf"
 
       - name: Convert User Guide HTML to PDF with Weasyprint
@@ -651,28 +641,21 @@ jobs:
         run: >
           dotnet weasyprint
           --pdf-variant pdf/a-3u
-          docs/requirements/requirements.html
+          docs/requirements_doc/requirements.html
           "docs/BuildMark Requirements.pdf"
 
       - name: Generate Trace Matrix PDF with Weasyprint
         run: >
           dotnet weasyprint
           --pdf-variant pdf/a-3u
-          docs/tracematrix/tracematrix.html
+          docs/requirements_report/trace_matrix.html
           "docs/BuildMark Trace Matrix.pdf"
 
-      - name: Convert Requirements Justifications HTML to PDF with Weasyprint
-        run: >
-          dotnet weasyprint
-          --pdf-variant pdf/a-3u
-          docs/justifications/justifications.html
-          "docs/BuildMark Requirements Justifications.pdf"
-
       - name: Convert Code Quality HTML to PDF with Weasyprint
         run: >
           dotnet weasyprint
           --pdf-variant pdf/a-3u
-          docs/quality/quality.html
+          docs/code_quality/quality.html
           "docs/BuildMark Code Quality.pdf"
 
       # === UPLOAD ARTIFACTS ===
@@ -685,4 +668,4 @@ jobs:
           name: documents
           path: |
             docs/*.pdf
-            docs/buildnotes.md
+            docs/build_notes.md

.github/workflows/release.yaml

@@ -69,7 +69,7 @@ jobs:
         with:
           tag: ${{ inputs.version }}
           artifacts: artifacts/*
-          bodyFile: artifacts/buildnotes.md
+          bodyFile: artifacts/build_notes.md
           generateReleaseNotes: false
 
       - name: Publish to NuGet.org

.gitignore

@@ -63,13 +63,13 @@ __pycache__/
 docs/**/*.html
 docs/**/*.pdf
 !docs/template/**
-docs/requirements/requirements.md
-docs/tracematrix/tracematrix.md
-docs/justifications/justifications.md
-docs/quality/sonar-quality.md
-docs/quality/codeql-quality.md
-docs/buildnotes.md
-docs/buildnotes/versions.md
+docs/requirements_doc/requirements.md
+docs/requirements_doc/justifications.md
+docs/requirements_report/trace_matrix.md
+docs/code_quality/sonar-quality.md
+docs/code_quality/codeql-quality.md
+docs/build_notes.md
+docs/build_notes/versions.md
 
 # VersionMark captures (generated during CI/CD)
 versionmark-*.json

AGENTS.md

@@ -159,7 +159,8 @@ integration, see the Requirements and Test Source Filters sections below.
 
 ## Key Files
 
-- **`requirements.yaml`** - All requirements with test linkage (enforced via `dotnet reqstream --enforce`)
+- **`requirements.yaml`** - Root requirements file using `includes:` to reference `docs/reqstream/` files
+- **`docs/reqstream/`** - Per-software-unit, platform, and OTS requirements YAML files
 - **`.editorconfig`** - Code style (file-scoped namespaces, 4-space indent, UTF-8, LF endings)
 - **`.cspell.yaml`, `.markdownlint-cli2.yaml`, `.yamllint.yaml`** - Linting configs
 
@@ -208,6 +209,16 @@ ensures the CI evidence comes specifically from the required environment.
 
 ## Project Structure
 
+- `docs/` - Documentation and compliance artifacts
+  - `reqstream/` - Per-software-unit, platform, and OTS requirements YAML files (included by root `requirements.yaml`)
+  - Auto-generated reports (requirements, justifications, trace matrix)
+- `src/` - Source code files
+- `test/` - Test files
+- `.github/workflows/` - CI/CD pipeline definitions (`build.yaml`, `build_on_push.yaml`, `release.yaml`)
+- Configuration files: `.editorconfig`, `.reviewmark.yaml`, `.cspell.yaml`, `.yamllint.yaml`, etc.
+
+### Key Source Files
+
 - **Context.cs**: Handles command-line argument parsing, logging, and output
 - **Program.cs**: Main entry point with version/help/validation routing
 - **Validation.cs**: Self-validation tests with TRX/JUnit output support
@@ -230,7 +241,7 @@ build.bat     # Windows
 ## Documentation
 
 - **User Guide**: `docs/guide/guide.md`
-- **Requirements**: `requirements.yaml` -> auto-generated docs
+- **Requirements**: `requirements.yaml` includes `docs/reqstream/` files → auto-generated docs
 - **Build Notes**: Auto-generated via BuildMark
 - **Code Quality**: Auto-generated via CodeQL and SonarMark
 - **Trace Matrix**: Auto-generated via ReqStream

THEORY-OF-OPERATIONS.md

@@ -226,7 +226,7 @@ stored in source control:
   run: |
     buildmark \
       --build-version ${{ inputs.version }} \
-      --report docs/buildnotes/build-notes.md
+      --report docs/build_notes/build-notes.md
 ```
 
 The generated report can then be uploaded as a build artifact, committed back to the repository, or

docs/build_notes/definition.yaml

@@ -0,0 +1,16 @@
+---
+resource-path:
+  - docs/build_notes
+  - docs/template
+
+input-files:
+  - docs/build_notes/title.txt
+  - docs/build_notes/introduction.md
+  - docs/build_notes.md
+  - docs/build_notes/versions.md
+
+template: template.html
+
+table-of-contents: true
+
+number-sections: true

docs/code_quality/definition.yaml

@@ -0,0 +1,16 @@
+---
+resource-path:
+  - docs/code_quality
+  - docs/template
+
+input-files:
+  - docs/code_quality/title.txt
+  - docs/code_quality/introduction.md
+  - docs/code_quality/codeql-quality.md
+  - docs/code_quality/sonar-quality.md
+
+template: template.html
+
+table-of-contents: true
+
+number-sections: true