Milestone 0: Repo scaffolding, governance, and CI/release automation

.github/CODEOWNERS

@@ -0,0 +1,14 @@
+# Default owner
+* @jeffpatton1971
+
+# Core engine
+/src/HelpGenerator.Core/ @jeffpatton1971
+
+# PowerShell layer
+/src/HelpGenerator.Powershell/ @jeffpatton1971
+
+# Documentation & ADRs
+/docs/ @jeffpatton1971
+
+# CI/CD workflows
+/.github/workflows/ @jeffpatton1971

.github/workflows/build.yml

@@ -0,0 +1,64 @@
+name: Build and Package (Preview)
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build_and_pack:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: ${{ vars.DOTNET_VERSION }}
+
+      - name: Get Project Version
+        id: get_version
+        uses: mod-posh/GetProjectVersion@main
+        with:
+          Filename: 'Directory.Build.props'
+          verbose: "verbose"
+
+      - name: Compose preview version parts
+        shell: pwsh
+        run: |
+          $sha7 = "${env:GITHUB_SHA}".Substring(0,7)
+          $prefix = "${{ steps.get_version.outputs.version }}"
+          if ([string]::IsNullOrWhiteSpace($prefix)) { $prefix = $env:VERSION }
+          if ([string]::IsNullOrWhiteSpace($prefix)) { throw "Could not resolve VersionPrefix" }
+
+          "VERSION_PREFIX=$prefix"                                  >> $env:GITHUB_ENV
+          "VERSION_SUFFIX=preview.${env:GITHUB_RUN_NUMBER}-g$sha7"  >> $env:GITHUB_ENV
+
+      - name: Clean
+        shell: pwsh
+        run: dotnet clean "${{ github.workspace }}/src/HelpGenerator.sln" --configuration Release
+
+      - name: Pack (preview)
+        shell: pwsh
+        run: >
+          dotnet pack "${{ github.workspace }}/src/HelpGenerator.sln"
+          --configuration Release
+          --output "${{ github.workspace }}/publish"
+          /m:1
+          -p:UseSharedCompilation=false
+          -p:ContinuousIntegrationBuild=true
+          -p:PackageVersion=${{ env.VERSION_PREFIX }}-${{ env.VERSION_SUFFIX }}
+          -p:RepositoryCommit=${{ github.sha }}
+          -p:RepositoryBranch=${{ github.ref_name }}
+
+      - name: List packages
+        shell: pwsh
+        run: |
+          Get-ChildItem -Path "${{ github.workspace }}/publish" |
+            ForEach-Object { Write-Host "Packaged: $($_.FullName)" }
+
+      - name: Upload packages as artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: preview-packages
+          path: publish/*.nupkg

.github/workflows/docs-pr.yml

@@ -0,0 +1,62 @@
+name: Docs PR After Release
+
+on:
+  workflow_run:
+    workflows: ["New Release"]
+    types:
+      - completed
+
+jobs:
+  docs_pr:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout Repository (main)
+        uses: actions/checkout@v6
+        with:
+          ref: main
+          fetch-depth: 0
+
+      - name: Get Latest Tag
+        id: latest_tag
+        run: |
+          LATEST_TAG=$(gh release list --limit 1 --json tagName --jq '.[0].tagName')
+          echo "LATEST_TAG=$LATEST_TAG" >> $GITHUB_ENV
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: ${{ vars.DOTNET_VERSION }}
+
+      # TODO: Replace with actual HelpGenerator docs generation when implemented.
+      - name: Generate Documentation (stub)
+        shell: bash
+        run: |
+          echo "Docs generation is currently stubbed."
+          echo "Replace this step once ${{ vars.PROJECT_NAME }} can generate docs."
+
+      - name: Create Pull Request with Docs Updates
+        uses: peter-evans/create-pull-request@v7
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: "Update docs for ${{ vars.PROJECT_NAME }} ${{ env.LATEST_TAG }}"
+          title: "Update docs for ${{ vars.PROJECT_NAME }} ${{ env.LATEST_TAG }}"
+          body: |
+            This PR updates generated documentation following release ${{ env.LATEST_TAG }}.
+
+            Notes:
+            - Generated via workflow: Docs PR After Release
+            - No code changes intended
+          branch: "docs/${{ env.LATEST_TAG }}"
+          base: main
+          delete-branch: true
+          add-paths: |
+            docs/**
+            README.md

.github/workflows/notifications.yml

@@ -0,0 +1,41 @@
+name: Announce New Release
+
+on:
+  workflow_run:
+    workflows: ["New Release"]
+    types:
+      - completed
+
+jobs:
+  send_notification:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+
+      - name: Get Latest Tag
+        id: latest_tag
+        run: |
+          LATEST_TAG=$(gh release list --limit 1 --json tagName --jq '.[0].tagName')
+          echo "latest_tag=$LATEST_TAG" >> $GITHUB_ENV
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Post to Bluesky
+        uses: mod-posh/Post2BlueSky@v0.0.3.0
+        with:
+          Message: |
+            Version ${{ env.latest_tag }} of ${{ vars.PROJECT_NAME }} is available! 🎉
+            See details here: ${{ github.server_url }}/${{ github.repository }}
+          verbose: "verbose"
+          bluesky_api_key: ${{ secrets.bluesky_api_key }}
+          bluesky_identifier: ${{ secrets.bluesky_identifier }}
+
+      - name: Post to Discord
+        uses: mod-posh/Post2Discord@v0.0.3.2
+        with:
+          message: |
+            Version ${{ env.latest_tag }} of ${{ vars.PROJECT_NAME }} is available! 🎉
+            See details here: ${{ github.server_url }}/${{ github.repository }}
+          discordWebhook: ${{ secrets.DISCORD_WEBHOOK }}

.github/workflows/release.yml

@@ -0,0 +1,83 @@
+name: New Release
+
+on:
+  milestone:
+    types: [closed]
+
+jobs:
+  create-release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository (main)
+        uses: actions/checkout@v6
+        with:
+          ref: main
+          fetch-depth: 0
+
+      - name: Get Project Version
+        id: get_version
+        uses: mod-posh/GetProjectVersion@main
+        with:
+          Filename: 'Directory.Build.props'
+          verbose: "verbose"
+
+      - name: Guardrail milestone title must match version
+        shell: pwsh
+        run: |
+          $milestoneTitle = '${{ github.event.milestone.title }}'.Trim()
+          $version = '${{ steps.get_version.outputs.version }}'.Trim()
+
+          if ([string]::IsNullOrWhiteSpace($milestoneTitle)) {
+            throw "Milestone title is empty. Refusing to create release."
+          }
+
+          if ([string]::IsNullOrWhiteSpace($version)) {
+            throw "Project version is empty. Refusing to create release."
+          }
+
+          if ($milestoneTitle -ne $version) {
+            throw "Refusing to create release: milestone title '$milestoneTitle' does not match project version '$version'."
+          }
+
+          Write-Host "Guardrail passed: milestone title '$milestoneTitle' matches version '$version'."
+
+      - name: Create Release Notes
+        uses: mod-posh/Issue2ReleaseNotes@v0.0.3.3
+        with:
+          milestone_number: ${{ github.event.milestone.number }}
+          verbose: 'verbose'
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create Release (Tag + GitHub Release)
+        uses: mod-posh/NewTaggedRelease@v0.0.3.2
+        with:
+          name: 'Release v${{ env.VERSION }}'
+          filename: 'RELEASE.md'
+          version: ${{ env.VERSION }}
+          verbose: 'verbose'
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: ${{ vars.DOTNET_VERSION }}
+
+      - name: Build
+        run: dotnet build "${{ github.workspace }}/src/${{ vars.PROJECT_NAME }}.sln" --configuration Release
+
+      - name: Test
+        run: dotnet test "${{ github.workspace }}/src/${{ vars.PROJECT_NAME }}.sln" --configuration Release --no-build
+
+      - name: Pack (Release)
+        run: dotnet pack "${{ github.workspace }}/src/${{ vars.PROJECT_NAME }}.sln" --configuration Release --output "${{ github.workspace }}/publish" --no-build
+
+      - name: Upload release packages
+        uses: actions/upload-artifact@v6
+        with:
+          name: release-packages
+          path: publish/*.nupkg
+
+      # PSGallery publishing will be added once the PowerShell module packaging is implemented.
+      # - name: Publish to PowerShell Gallery
+      #   shell: pwsh
+      #   run: Publish-Module ...

.github/workflows/test.yml

@@ -0,0 +1,41 @@
+name: Merge Test Workflow
+
+on:
+  pull_request:
+    branches:
+      - main
+      - "milestone/**"
+
+jobs:
+  run_tests:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: ${{ vars.DOTNET_VERSION }}
+
+      - name: Clean
+        shell: pwsh
+        run: dotnet clean "${{ github.workspace }}/src/HelpGenerator.sln" --configuration Release
+
+      - name: Restore dependencies
+        shell: pwsh
+        run: dotnet restore "${{ github.workspace }}/src/HelpGenerator.sln"
+
+      - name: Build
+        shell: pwsh
+        run: dotnet build "${{ github.workspace }}/src/HelpGenerator.sln" --configuration Release --no-restore
+
+      - name: Test
+        shell: pwsh
+        run: dotnet test "${{ github.workspace }}/src/HelpGenerator.sln" --configuration Release --no-build --logger "trx;LogFileName=test_results.trx"
+
+      - name: Publish Test Results
+        if: always()
+        uses: actions/upload-artifact@v6
+        with:
+          name: Test Results
+          path: '**/TestResults/*.trx'