Add build.ps1 -CommitArtifacts switch for source/artifact lockstep commits

New switch stages and commits only the three build-output paths (Module/PSInfisicalAPI/bin/**, Module/PSInfisicalAPI/PSInfisicalAPI.psd1, CHANGELOG.md) with a message referencing the embedded BuildCommitHash. Mutually exclusive with -CommitOnSuccess. README and CHANGELOG updated to document the recommended two-commit workflow.

CHANGELOG.md

@@ -6,29 +6,31 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) loos
 
 ## Unreleased
 
+- `build.ps1` gains a `-CommitArtifacts` switch that, after a successful build, stages and commits only the build outputs (`Module/PSInfisicalAPI/bin/**`, `Module/PSInfisicalAPI/PSInfisicalAPI.psd1`, and the auto-inserted `CHANGELOG.md` build stamp) with a message that references the source commit whose hash is now embedded in `BuildCommitHash`. The switch is mutually exclusive with the older broader `-CommitOnSuccess` (which still uses `git add -A`). README extended with a "Committing source and build artifacts in lockstep" section describing the recommended two-commit workflow.
+
 ## 2026.06.04.1917
 
 - Build produced from commit a34db831d8bf.
 
-## Unreleased (carried forward)
+## Unreleased (carried forward)
 
 ## 2026.06.04.1915
 
 - Build produced from commit 2489b7adca98.
 
-## Unreleased (carried forward)
+## Unreleased (carried forward)
 
 ## 2026.06.04.1911
 
 - Build produced from commit 51bf819c37e5.
 
-## Unreleased (carried forward)
+## Unreleased (carried forward)
 
 ## 2026.06.04.1906
 
 - Build produced from commit 51bf819c37e5.
 
-## Unreleased (carried forward)
+## Unreleased (carried forward)
 
 - **BREAKING**: Removed the plural-noun discovery cmdlets `Get-InfisicalProjects`, `Get-InfisicalEnvironments`, `Get-InfisicalFolders`, `Get-InfisicalTags`, `Get-InfisicalSecrets`, and `Get-InfisicalCertificates`. Their behavior is now folded into the corresponding singular cmdlets via a `List` (default) / single-record parameter set pair, matching the existing `Get-InfisicalCertificateAuthority` precedent. Callers should drop the trailing `s`; invocation without the identity parameter (`-ProjectId`, `-EnvironmentSlugOrId`, `-FolderNameOrId`, `-TagSlugOrId`, `-SecretName`, `-SerialNumber`) now returns the list, and supplying the identity parameter returns the single record. No back-compat aliases were added.
 - Added `Get-InfisicalPkiSubscriber` with `List` (default) and `ByName` parameter sets, backed by new `InfisicalPkiClient.ListPkiSubscribers` and `GetPkiSubscriber` methods, an `InfisicalPkiSubscriber` model, and corresponding DTOs/mapper. Use the emitted `Name` (slug) on `Request-InfisicalCertificate -PkiSubscriberSlug`.

README.md

@@ -230,6 +230,16 @@ After adding (or removing) a cmdlet:
 4. Add a `## Unreleased` entry to `CHANGELOG.md` describing the change (mark removals of public cmdlets or parameters as **BREAKING**).
 5. Run `./build.ps1 -RunTests`. The script enforces the cmdlet list, runs the xUnit suite, and verifies that every exported cmdlet has a valid synopsis, description, and at least one non-empty example.
 
+### Committing source and build artifacts in lockstep
+
+The embedded `BuildCommitHash` in `Module/PSInfisicalAPI/PSInfisicalAPI.psd1` and the bundled DLL is captured from `git rev-parse HEAD` at build time. To keep the embedded hash truthful, commit source and build artifacts as two ordered commits:
+
+1. Stage and commit your source changes first. Suppose this produces commit `S`.
+2. Run `./build.ps1 -RunTests -CommitArtifacts`. The build picks up `S` as `HEAD`, embeds it as `BuildCommitHash`, then stages and commits **only** the build outputs (`Module/PSInfisicalAPI/bin/**`, `Module/PSInfisicalAPI/PSInfisicalAPI.psd1`, and the `CHANGELOG.md` build-stamp insertion). The commit message references `S` so the binary commit always traces back to its source.
+3. `git push`.
+
+`-CommitArtifacts` only touches the three artifact paths above; any other dirty files in your working tree are left alone. Use the older `-CommitOnSuccess` switch only when you intentionally want a single commit covering everything (`git add -A` + `git commit -m "Build <version>"`); the two switches are mutually exclusive.
+
 ## Continuous integration
 
 `.gitea/workflows/publish-psgallery.yml` publishes the module to the PowerShell Gallery whenever a pull request is merged into `main`. The workflow expects a repository secret named `PSGALLERY_API_KEY` containing a valid Gallery API key.

build.ps1

@@ -15,9 +15,15 @@ param(
 
     [switch]$CommitOnSuccess,
 
+    [switch]$CommitArtifacts,
+
     [switch]$Force
 )
 
+if ($CommitOnSuccess.IsPresent -and $CommitArtifacts.IsPresent) {
+    throw "-CommitOnSuccess and -CommitArtifacts are mutually exclusive."
+}
+
 $ErrorActionPreference = 'Stop'
 Set-StrictMode -Version Latest
 
@@ -390,4 +396,30 @@ if ($CommitOnSuccess.IsPresent) {
     if ($LASTEXITCODE -ne 0) { throw "git commit failed." }
 }
 
+if ($CommitArtifacts.IsPresent) {
+    Write-Step "Committing build artifacts (embedded BuildCommitHash=$commitHash)"
+    $artifactPaths = @(
+        [System.IO.Path]::Combine('Module', 'PSInfisicalAPI', 'bin'),
+        [System.IO.Path]::Combine('Module', 'PSInfisicalAPI', 'PSInfisicalAPI.psd1'),
+        'CHANGELOG.md'
+    )
+
+    foreach ($artifactPath in $artifactPaths) {
+        & git -C $RepositoryRoot.FullName add -- $artifactPath
+        if ($LASTEXITCODE -ne 0) { throw "git add '$artifactPath' failed." }
+    }
+
+    $stagedOutput = & git -C $RepositoryRoot.FullName diff --cached --name-only
+    if ($LASTEXITCODE -ne 0) { throw "git diff --cached failed." }
+    $stagedFiles = @($stagedOutput | Where-Object { -not [string]::IsNullOrWhiteSpace($_) })
+    if ($stagedFiles.Count -eq 0) {
+        Write-Step "No build artifact changes to commit."
+    } else {
+        $subject = "Build artifacts for $commitHash"
+        $body    = "Auto-generated by build.ps1 -CommitArtifacts. Build $buildVersion. Module DLL and manifest embed BuildCommitHash=$commitHash, matching the source commit they were produced from."
+        & git -C $RepositoryRoot.FullName commit -m $subject -m $body
+        if ($LASTEXITCODE -ne 0) { throw "git commit failed." }
+    }
+}
+
 Write-Step "Build complete."