fix(release-script): guard the list that stages the showcase, and put back what the post-release pass rewrote (#703)

Two holes around web/showcase, both surfaced by cutting v2.4.1.

The release commit's staging list is now built by Get-ReleaseCommitPathspecs
rather than inline, and release-script-check.yml lifts it by AST and runs it for
real: a list carrying any :(exclude), one that stops naming web/showcase, or one
whose `git add --dry-run` leaves a rewritten showcase file out now fails the
check. The step that already owned these pathspecs runs Get-GeneratedPagePathspecs
on its own, where the exclusion is correct - which is why it stayed green while
the release commit was losing 133 files. Proven against three sabotages: the
exclusion put back as :(exclude)web/showcase, caught by the pattern; the entry
narrowed to web/showcase/pdf, caught by the name; and the exclusion written
:(exclude,glob)web/showcase/**, which the pattern does not match and the dry run
catches.

-PostReleaseOnly rebuilt every preview through Sync-ShowcaseSite and committed
none of them - those belong to the tag - but nothing put them back, so the
documented last step of every release left ~125 modified files behind, which the
runbook reads as the signature of a bumped-but-unstaged file. Restore-CommittedShowcase
restores them, tracked files only, so a preview for an example added since the tag
survives.

The post-release `add` is split the same way as the release one. Nothing in its
list stands under the showcase today, so its exclusion cancels nothing - but a
path added there later would be dropped in silence, which is the defect above.

ReleaseAssetStepGuardTest compared the source offset of the `knowledge` staging
literal against Step 5c. That literal now sits in the extracted function, above the
flow, so the comparison is against the call that builds the list - where the
staging actually happens.

Author: DemchaAV

.github/workflows/release-script-check.yml

@@ -530,6 +530,50 @@ jobs:
           if (git status --porcelain -- web) { throw 'the probe left the web/ tree changed' }
           Write-Host 'page staging: the documentation page and a rewritten, a deleted and an added card page are staged, and nothing under web/showcase/.'
 
+      - name: The cut stages the showcase assets its own regeneration rewrote
+        shell: pwsh
+        run: |
+          # The step above proves the page globs are right on their own - which they were
+          # throughout. This one proves the list they used to stand in stages what it names.
+          # Get-ReleaseCommitPathspecs builds every path of the release commit bar the pages, and
+          # goes to one `git add`. The page globs carry :(exclude)web/showcase, and git applies an
+          # exclude to the WHOLE invocation rather than to the pathspecs beside it: while the two
+          # lists were one, the exclude cancelled the explicit web/showcase entry, and the v2.4.1
+          # release commit carried none of the 133 showcase files its own Step 4c had just
+          # rewritten. Lifted by AST and run for real - a list that stages nothing under
+          # web/showcase fails here, before a cut can tag it.
+          $path = (Resolve-Path scripts/cut-release.ps1).Path
+          $ast = [System.Management.Automation.Language.Parser]::ParseFile($path, [ref]$null, [ref]$null)
+          $fn = $ast.FindAll({
+              param($n)
+              $n -is [System.Management.Automation.Language.FunctionDefinitionAst] -and $n.Name -eq 'Get-ReleaseCommitPathspecs'
+            }, $true) | Select-Object -First 1
+          if (-not $fn) { throw 'cut-release.ps1 no longer defines Get-ReleaseCommitPathspecs' }
+          Invoke-Expression $fn.Extent.Text
+          $repoRoot = (Get-Location).Path
+          $list = @(Get-ReleaseCommitPathspecs $true $false)
+
+          # An exclude anywhere in this list reaches every path in the same add, whatever it was
+          # written to narrow, so none may stand in it at all.
+          $excludes = @($list | Where-Object { $_ -like '*:(exclude*' -or $_ -like ':!*' })
+          if ($excludes) { throw "the release staging list carries an exclude pathspec: $($excludes -join ', ')" }
+          if ($list -notcontains 'web/showcase') { throw 'the release staging list no longer names web/showcase' }
+
+          $showcaseFile = @(git ls-files -- web/showcase)[0]
+          if (-not $showcaseFile) { throw 'expected committed files under web/showcase' }
+          try {
+            Add-Content -Path $showcaseFile -Value 'touched'
+            $staged = @(git add --dry-run -- @($list))
+            if ($LASTEXITCODE -ne 0) { throw 'git add --dry-run refused the release staging list' }
+            if (-not ($staged -contains "add '$showcaseFile'")) {
+              throw "the release staging list leaves $showcaseFile out; a regenerated showcase would miss the release commit"
+            }
+          } finally {
+            git checkout -- $showcaseFile
+          }
+          if (git status --porcelain -- web/showcase) { throw 'the probe left web/showcase changed' }
+          Write-Host 'release staging: a rewritten showcase file is staged, and the list carries no exclude pathspec.'
+
       - name: Unit-check the roadmap promotion (refusals and the real rewrite)
         shell: pwsh
         run: |

core/src/test/java/com/demcha/documentation/ReleaseAssetStepGuardTest.java

@@ -183,6 +183,10 @@ void theCutRegeneratesTheKnowledgeSurfacesBeforeStagingThem() throws IOException
 
         int regen = script.indexOf("Step \"5c\" \"Regenerate the knowledge pack surfaces");
         int staged = script.indexOf("$commitFiles += 'knowledge'");
+        // The list is built by Get-ReleaseCommitPathspecs, declared with the other functions near
+        // the top of the script, so where the literal above sits no longer says when the staging
+        // happens — its call does. Read against that call, this is the order the cut executes in.
+        int stagingCall = script.indexOf("$commitFiles = @(Get-ReleaseCommitPathspecs");
 
         assertThat(regen)
                 .describedAs("the cut no longer regenerates the knowledge surfaces, so the release "
@@ -193,10 +197,14 @@ void theCutRegeneratesTheKnowledgeSurfacesBeforeStagingThem() throws IOException
                 .describedAs("the release commit no longer stages knowledge/, so a regen would happen "
                         + "and never reach the tag")
                 .isNotNegative();
+        assertThat(stagingCall)
+                .describedAs("the release commit no longer builds its staging list through "
+                        + "Get-ReleaseCommitPathspecs, so this ordering reads nothing")
+                .isNotNegative();
         assertThat(regen)
                 .describedAs("the surfaces are regenerated after the commit that stages them, so the "
                         + "tag carries the previous version's pack")
-                .isLessThan(staged);
+                .isLessThan(stagingCall);
     }
 
     @Test