Pre-release quality sweep: all agents and template synchronization

.config/dotnet-tools.json

@@ -39,7 +39,7 @@
       ]
     },
     "demaconsulting.buildmark": {
-      "version": "0.2.0",
+      "version": "0.3.0",
       "commands": [
         "buildmark"
       ]

.cspell.json

@@ -7,8 +7,10 @@
     "buildmark",
     "BuildMark",
     "buildnotes",
+    "buildtransitive",
     "camelcase",
     "CodeQL",
+    "contentfiles",
     "copilot",
     "coveragexml",
     "cspell",
@@ -26,6 +28,7 @@
     "dotnet",
     "dotnettool",
     "editorconfig",
+    "errorlevel",
     "filepart",
     "fsproj",
     "Gidget",

.editorconfig

@@ -6,6 +6,7 @@ root = true
 # All files
 [*]
 charset = utf-8
+end_of_line = lf
 indent_style = space
 indent_size = 4
 insert_final_newline = true

.github/workflows/build.yaml

@@ -351,14 +351,12 @@ jobs:
       contents: read
 
     steps:
+      # === CHECKOUT AND DOWNLOAD ARTIFACTS ===
+      # This section retrieves the code and all necessary artifacts from previous jobs.
+
       - name: Checkout
         uses: actions/checkout@v6
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: 'lts/*'
-
       - name: Download all test results
         uses: actions/download-artifact@v7
         with:
@@ -385,6 +383,14 @@ jobs:
           pattern: 'version-capture-*'
         continue-on-error: true
 
+      # === INSTALL DEPENDENCIES ===
+      # This section installs all required dependencies and tools for document generation.
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 'lts/*'
+
       - name: Setup dotnet
         uses: actions/setup-dotnet@v5
         with:
@@ -405,6 +411,9 @@ jobs:
       - name: Restore Tools
         run: dotnet tool restore
 
+      # === CAPTURE TOOL VERSIONS ===
+      # This section captures the versions of all tools used in the build process.
+
       - name: Capture tool versions for build-docs
         shell: bash
         run: |
@@ -413,6 +422,9 @@ jobs:
             dotnet git node npm pandoc weasyprint sarifmark reqstream buildmark versionmark
           echo "✓ Tool versions captured"
 
+      # === GENERATE MARKDOWN REPORTS ===
+      # This section generates all markdown reports from various tools and sources.
+
       - name: Generate Requirements Report and Trace Matrix
         run: >
           dotnet reqstream
@@ -438,70 +450,6 @@ jobs:
           echo "=== CodeQL Quality Report ==="
           cat docs/quality/codeql-quality.md
 
-      - name: Generate HTML with Pandoc
-        run: >
-          dotnet pandoc
-          --defaults docs/guide/definition.yaml
-          --filter node_modules/.bin/mermaid-filter.cmd
-          --metadata version="${{ inputs.version }}"
-          --metadata date="$(date +'%Y-%m-%d')"
-          --output docs/guide/guide.html
-
-      - name: Generate PDF with Weasyprint
-        run: >
-          dotnet weasyprint
-          --pdf-variant pdf/a-3u
-          docs/guide/guide.html
-          "docs/SonarMark User Guide.pdf"
-
-      - name: Generate Requirements HTML with Pandoc
-        run: >
-          dotnet pandoc
-          --defaults docs/requirements/definition.yaml
-          --filter node_modules/.bin/mermaid-filter.cmd
-          --metadata version="${{ inputs.version }}"
-          --metadata date="$(date +'%Y-%m-%d')"
-          --output docs/requirements/requirements.html
-
-      - name: Generate Requirements PDF with Weasyprint
-        run: >
-          dotnet weasyprint
-          --pdf-variant pdf/a-3u
-          docs/requirements/requirements.html
-          "docs/SonarMark Requirements.pdf"
-
-      - name: Generate Trace Matrix HTML with Pandoc
-        run: >
-          dotnet pandoc
-          --defaults docs/tracematrix/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 Trace Matrix PDF with Weasyprint
-        run: >
-          dotnet weasyprint
-          --pdf-variant pdf/a-3u
-          docs/tracematrix/tracematrix.html
-          "docs/SonarMark Trace Matrix.pdf"
-
-      - name: Generate Justifications HTML with Pandoc
-        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
-
-      - name: Generate Justifications PDF with Weasyprint
-        run: >
-          dotnet weasyprint
-          --pdf-variant pdf/a-3u
-          docs/justifications/justifications.html
-          "docs/SonarMark Requirements Justifications.pdf"
-
       - name: Generate Code Quality Report with SonarMark
         shell: bash
         env:
@@ -536,11 +484,6 @@ jobs:
         run: |
           echo "=== Build Notes Report ==="
           cat docs/buildnotes.md
-          # Verify buildnotes.md was created
-          if [ ! -f "docs/buildnotes.md" ]; then
-            echo "Error: buildnotes.md was not created"
-            exit 1
-          fi
 
       - name: Publish Tool Versions
         shell: bash
@@ -556,6 +499,45 @@ jobs:
           echo "=== Tool Versions Report ==="
           cat docs/buildnotes/versions.md
 
+      # === GENERATE HTML DOCUMENTS WITH PANDOC ===
+      # This section converts markdown documents to HTML using Pandoc.
+
+      - name: Generate Guide HTML with Pandoc
+        run: >
+          dotnet pandoc
+          --defaults docs/guide/definition.yaml
+          --filter node_modules/.bin/mermaid-filter.cmd
+          --metadata version="${{ inputs.version }}"
+          --metadata date="$(date +'%Y-%m-%d')"
+          --output docs/guide/guide.html
+
+      - name: Generate Requirements HTML with Pandoc
+        run: >
+          dotnet pandoc
+          --defaults docs/requirements/definition.yaml
+          --filter node_modules/.bin/mermaid-filter.cmd
+          --metadata version="${{ inputs.version }}"
+          --metadata date="$(date +'%Y-%m-%d')"
+          --output docs/requirements/requirements.html
+
+      - name: Generate Trace Matrix HTML with Pandoc
+        run: >
+          dotnet pandoc
+          --defaults docs/tracematrix/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 Justifications HTML with Pandoc
+        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
+
       - name: Generate Build Notes HTML with Pandoc
         shell: bash
         run: >
@@ -566,13 +548,6 @@ jobs:
           --filter node_modules/.bin/mermaid-filter.cmd
           --output docs/buildnotes/buildnotes.html
 
-      - name: Convert Build Notes HTML to PDF with Weasyprint
-        run: >
-          dotnet weasyprint
-          --pdf-variant pdf/a-3u
-          docs/buildnotes/buildnotes.html
-          "docs/SonarMark Build Notes.pdf"
-
       - name: Generate Code Quality HTML with Pandoc
         run: >
           dotnet pandoc
@@ -582,13 +557,54 @@ jobs:
           --metadata date="$(date +'%Y-%m-%d')"
           --output docs/quality/quality.html
 
+      # === GENERATE PDF DOCUMENTS WITH WEASYPRINT ===
+      # This section converts HTML documents to PDF using Weasyprint.
+
+      - name: Generate Guide PDF with Weasyprint
+        run: >
+          dotnet weasyprint
+          --pdf-variant pdf/a-3u
+          docs/guide/guide.html
+          "docs/SonarMark User Guide.pdf"
+
+      - name: Generate Requirements PDF with Weasyprint
+        run: >
+          dotnet weasyprint
+          --pdf-variant pdf/a-3u
+          docs/requirements/requirements.html
+          "docs/SonarMark Requirements.pdf"
+
+      - name: Generate Trace Matrix PDF with Weasyprint
+        run: >
+          dotnet weasyprint
+          --pdf-variant pdf/a-3u
+          docs/tracematrix/tracematrix.html
+          "docs/SonarMark Trace Matrix.pdf"
+
+      - name: Generate Justifications PDF with Weasyprint
+        run: >
+          dotnet weasyprint
+          --pdf-variant pdf/a-3u
+          docs/justifications/justifications.html
+          "docs/SonarMark Requirements Justifications.pdf"
+
+      - name: Generate Build Notes PDF with Weasyprint
+        run: >
+          dotnet weasyprint
+          --pdf-variant pdf/a-3u
+          docs/buildnotes/buildnotes.html
+          "docs/SonarMark Build Notes.pdf"
+
       - name: Generate Code Quality PDF with Weasyprint
         run: >
           dotnet weasyprint
           --pdf-variant pdf/a-3u
           docs/quality/quality.html
           "docs/SonarMark Code Quality.pdf"
 
+      # === UPLOAD ARTIFACTS ===
+      # This section uploads all generated documentation artifacts.
+
       - name: Upload documentation
         uses: actions/upload-artifact@v6
         with:

.github/workflows/build_on_push.yaml

@@ -11,10 +11,10 @@ jobs:
   build:
     name: Build
     permissions:
-      actions: read             # To read workflow artifacts
-      contents: read            # To read repository contents
-      pull-requests: write      # To write pull requests analysis results and artifacts
-      security-events: write    # To upload CodeQL results
+      actions: read
+      contents: read
+      pull-requests: write
+      security-events: write
     uses: ./.github/workflows/build.yaml
     with:
       version: 0.0.0-run.${{ github.run_number }}

.github/workflows/release.yaml

@@ -18,19 +18,23 @@ on:
           - publish
 
 jobs:
+  # Calls the reusable build workflow to build, test, and generate documentation
+  # for the release version.
   build:
     name: Build
     permissions:
-      actions: read             # To read workflow artifacts
-      contents: read            # To read repository contents
-      pull-requests: write      # To write pull requests analysis results and artifacts
-      security-events: write    # To upload CodeQL results
+      actions: read
+      contents: read
+      pull-requests: write
+      security-events: write
     uses: ./.github/workflows/build.yaml
     with:
       version: ${{ inputs.version }}
     secrets:
       SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
 
+  # Cuts and publishes the release, creating a GitHub release with artifacts
+  # and optionally publishing the NuGet package.
   release:
     name: Release
     runs-on: ubuntu-latest
@@ -62,10 +66,6 @@ jobs:
       - name: Move buildnotes.md to root
         run: |
           set -e
-          if [ ! -f "artifacts/buildnotes.md" ]; then
-            echo "Error: buildnotes.md not found in artifacts"
-            exit 1
-          fi
           mv artifacts/buildnotes.md buildnotes.md
 
       - name: Create GitHub Release

.gitignore

@@ -56,4 +56,8 @@ docs/justifications/*.html
 docs/quality/sonar-quality.md
 docs/quality/codeql-quality.md
 docs/quality/*.html
+docs/buildnotes.md
 docs/buildnotes/versions.md
+
+# VersionMark captures (generated during CI/CD)
+versionmark-*.json

.markdownlint-cli2.jsonc

@@ -1,14 +1,13 @@
 {
-  // Markdown linting configuration for markdownlint-cli2
   "config": {
     "default": true,
     "MD003": { "style": "atx" },
     "MD007": { "indent": 2 },
     "MD013": { "line_length": 120 },
+    "MD025": false,
     "MD033": false,
     "MD041": false
   },
-  // Ignore patterns
   "ignores": [
     "node_modules",
     "**/AGENT_REPORT_*.md"

.yamllint.yaml

@@ -4,6 +4,11 @@
 
 extends: default
 
+# Ignore node_modules and other generated/third-party directories
+ignore: |
+  node_modules/
+  .git/
+
 rules:
   # Allow 'on:' in GitHub Actions workflows (not a boolean value)
   truthy: