chore(memory-bank): record the release process and the 5.0.0-rc1 plan

- Decision 12: releases are built and published by CI on a version
  tag, prerelease first; Decision 10 gains the prerelease rule.
- techContext and systemPatterns: the release job, the packages, the
  command tags, and the new tests.
- progress and activeContext: #97 merged, the release PR, and the steps
  for the maintainer.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>

.memory-bank/activeContext.md

@@ -9,30 +9,36 @@ source: current task evidence
 
 ## Current focus
 
-PRs #94, #95, and #96 are merged; CI and the wiki run on GitHub Actions.
+Release 5.0.0 through CI, with the prerelease `5.0.0-rc1` first
-The version history completed from the PowerShell Gallery packages is
+(Decision 12). The release workflow, scripts, tests, and docs are PR-ready
-PR-ready on the local branch `ai/version-history`; the maintainer pushes it
+on the local branch `ai/release-5.0.0`; the maintainer pushes it, opens the
-and opens the PR. Work package 5 (code defects) waits for the maintainer's
+PR, sets up the Gallery key and the environment `powershell-gallery`, and
-go-ahead.
+tags `5.0.0-rc1` after the merge. Work package 5 (code defects) and the
+open issues come after the release.
 
 ## Evidence
 
-- Six Gallery packages compared (4.0.0, 4.2.2 to 4.2.6), each imported in
+- Test first: `Tests\Release.Tests.ps1` failed 15 of 15 (Windows
-  its own Windows PowerShell process: exported cmdlets 30, 35, 36, 36, 36,
+  PowerShell: 9 failed, 6 skipped) before the scripts existed; the command
-  36. `Show-SimpleAccess` was exported only by 4.0.0 (the manifest of 4.2.2
+  tag test failed before the tags were added. Final: full suite 268 tests,
-  to 4.2.4 lists it as `Show-NTFSSimpleAccess`) and deleted in 4.2.5. All
+  PowerShell 7 232 passed and 36 skipped, Windows PowerShell 261 passed and
-  versions export the aliases `dir2`, `gi2`, `rm2`, and `del2` only.
+  7 skipped (packaging needs PowerShell 7).
-- 4.2.4 already carried the MIT license (`LicenseUri`), the setting
+- Package dry run: `NTFSSecurity.5.0.0-rc1.nupkg` (about 275 KB) with the 11
-  `IdentifyHardLinks`, and AlphaFS 2.2.1; 4.2.5 fixed the `-Account`
+  `FileList` files, version `5.0.0-rc1`, release notes link, and 83 tags
-  aliases (#18, #36) and #48 but broke the `Applies to` column, which 4.2.6
+  (36 `PSCmdlet_`, 36 `PSCommand_`, `PSIncludes_Cmdlet`); the extracted
-  fixed (#57). 4.2.5 and 4.2.6 still ship AlphaFS 2.2.1: `d8f67af` updated
+  package imports in Windows PowerShell 5.1 and PowerShell 7.6.1 with 36
-  only `packages.config`, not the `HintPath`.
+  cmdlets and working help. 4.2.6 on the Gallery has 37 + 37 command tags;
-- `Wiki.Tests.ps1` passes with the changed page; markdownlint (with `MD024`
+  PSResourceGet 1.2.0 `Compress-PSResource` adds none.
-  siblings only for `CHANGELOG.md`) and the link check found nothing.
+- actionlint, PSScriptAnalyzer, and markdownlint: no findings.
+- `master` has 37 open issues; several overlap the work package 5 defects
+  (for example #4) or are already fixed (#19 in 4.2.4; #15, #47, #66 by the
+  documentation).
 - The local branch `ai/read-the-docs` keeps the dropped strict-build work
   (`886c874`, `325ec76`); delete it once it is no longer wanted.
 
 ## Next step
 
-After the maintainer opens the PR: read its GitHub Actions run with
+After the maintainer opens the PR: read its CI run, and download the
-`gh pr checks`. Then wait for the go-ahead for work package 5.
+`packages` artifact (`gh run download`) to compare it with the local dry
+run. After the `5.0.0-rc1` tag: check the release job, the Gallery entry
+(version, tags, `Find-Command Get-NTFSAccess`), and the GitHub prerelease.

.memory-bank/decisions/0010-one-version.md

@@ -8,17 +8,22 @@ source: maintainer decisions in work package 4
 
 # Decision 10: One version for the manifest, assemblies, and changelog
 
-- Choice: `ModuleVersion` in `NTFSSecurity.psd1`, `AssemblyVersion` and
+- Choice: `ModuleVersion` in `NTFSSecurity.psd1` and `AssemblyVersion` and
   `AssemblyFileVersion` of `NTFSSecurity`, `Security2`, and
-  `PrivilegeControl` (as `x.y.z.0`), and the latest version section of
+  `PrivilegeControl` (as `x.y.z.0`) carry the same version
-  `CHANGELOG.md` carry the same version. The vendored `ProcessPrivileges`
+  (`Tests\Manifest.Tests.ps1`). The vendored `ProcessPrivileges` and the
-  and the unshipped `Log` keep their own versions.
+  unshipped `Log` keep their own versions. `CHANGELOG.md` describes that
-  `Tests\Manifest.Tests.ps1` enforces this.
+  version (`Tests\Release.Tests.ps1` through `Get-ReleaseInfo.ps1`): a
+  release has a dated section `## [x.y.z] - yyyy-MM-dd`; a prerelease has
+  its label in `PrivateData.PSData.Prerelease` and its notes under
+  `## [Unreleased]`, with no section for `x.y.z` yet (changelog Option A,
+  amended 2026-10-04 for the 5.0.0 prerelease).
 - Rationale: Before, the manifest said 4.2.5, the release 4.2.6, and the
   assemblies 4.2.1.0, 3.2.3.0, and 1.0.0.0; releases bumped the version
   only in the published copy. One version, set in the repository before
   the release, identifies a build.
-- Consequence: A version bump changes all five places in one commit. The
+- Consequence: A version bump changes the manifest and three assemblies in
-  date of the version section is the release date; update it when you tag.
+  one commit. The final release renames `[Unreleased]` to the dated version
+  section and removes the prerelease label.
 - Context: 5.0.0 is major because the minimum PowerShell version rose to
   5.1. `Remove-Item2 -PassThur` stays as a deprecated alias of `-PassThru`.

.memory-bank/decisions/0012-ci-releases.md

@@ -0,0 +1,39 @@
+---
+status: accepted
+date: 2026-10-04
+last-verified: 2026-10-04
+owner: shared
+source: maintainer decisions after #97 (release first, prerelease first)
+---
+
+# Decision 12: Releases are built and published by CI on a version tag
+
+- Choice: Pushing a tag such as `5.0.0` or `5.0.0-rc1` on `master` runs the
+  `release` job of `.github/workflows/ci.yml`. It publishes the package that
+  the `build` job built and tested to the PowerShell Gallery
+  (`Publish-PSResource -NupkgPath`) and creates the GitHub release with
+  `NTFSSecurity.zip`, marked as a prerelease for a prerelease tag. The job
+  checks that the tag equals the manifest version (with the prerelease
+  label) and points to a commit on `master`, and it skips a version the
+  Gallery or GitHub already has, so a rerun is safe.
+- Package: `New-ModulePackage.ps1` copies only the `FileList` files of the
+  Release build, so no `.pdb`, XML documentation, or
+  `System.Management.Automation.dll` ships. `Compress-PSResource` builds the
+  nupkg; the script adds the command tags (`PSIncludes_Cmdlet`,
+  `PSCmdlet_<name>`, `PSCommand_<name>`) that PowerShellGet 2 added and
+  PSResourceGet 1.2 doesn't, because the Gallery lists cmdlets and
+  `Find-Command` searches by them. Every CI run builds the packages, so pull
+  requests test them.
+- Secret: `PSGALLERY_API_KEY` belongs to the GitHub environment
+  `powershell-gallery`, which only the `release` job uses; the maintainer
+  creates the key, the environment, and the secret, and may require a
+  reviewer.
+- Process: a prerelease first (maintainer, 2026-10-04: "no full release
+  without proper testing"), starting with `5.0.0-rc1`; the final release
+  removes the label and dates the changelog section. Steps for maintainers
+  are in `Docs/Contributing/05-Releasing.md`.
+- Rationale: Releases so far were local Debug builds published by hand
+  with the whole output folder; tags carried the previous version.
+- Rejected: publishing with PowerShellGet 2 `Publish-Module` (repackages at
+  publish time, so the tested package isn't the published one), and adding
+  the command tags to the shipped manifest.

.memory-bank/progress.md

@@ -9,12 +9,12 @@ source: repository evidence
 
 ## Current status
 
-PRs #91 to #96 are merged; `master` (`4f9f7cc`) carries version 5.0.0,
+PRs #91 to #97 are merged; `master` (`59663c9`) carries version 5.0.0,
 which is not released yet. CI runs on GitHub Actions: build, docs checks,
 and tests in Windows PowerShell 5.1 and PowerShell 7, plus the wiki, which
-is generated from `Docs` (43 pages). AppVeyor no longer reports on `master`.
+is generated from `Docs` (43 pages). PR-ready locally: `ai/release-5.0.0`,
-PR-ready locally: `ai/version-history`, the version history completed from
+releases by CI on a version tag (Decision 12), starting with the
-the PowerShell Gallery packages.
+prerelease `5.0.0-rc1`.
 
 ## Recent milestones
 
@@ -43,9 +43,15 @@ the PowerShell Gallery packages.
   the wiki (`62ec94a`, 43 pages).
 - 2026-10-04: The maintainer kept the version history separate from
   `CHANGELOG.md` and had it completed from the six PowerShell Gallery
-  packages and the commit history: release dates, notes for 4.2.2, detailed
+  packages and the commit history (#97, `59663c9`): release dates, notes
-  notes for 4.2.4, and separate notes for 4.2.5 and 4.2.6
+  for 4.2.2, detailed notes for 4.2.4, and separate notes for 4.2.5 and
-  (`ai/version-history`).
+  4.2.6. The wiki republished it.
+- 2026-10-04: The maintainer chose to release 5.0.0 next, through CI and a
+  prerelease first (Decision 12): `ai/release-5.0.0` adds the `release` job,
+  `Get-ReleaseInfo.ps1`, `New-ModulePackage.ps1`, `Tests\Release.Tests.ps1`,
+  the label `rc1`, and `Docs/Contributing/05-Releasing.md`. The package
+  dry run found that PSResourceGet drops the command tags that 4.2.6 had;
+  the script adds them back.
 
 ## Stable capabilities
 
@@ -65,19 +71,22 @@ next package starts only after the maintainer's go-ahead.
 1. Housekeeping: done (#92).
 2. Ship help: done (#93).
 3. Docs on GitHub: done (#94).
-4. Manifest and version 5.0.0: done (#95). Before the release: set the date
+4. Manifest and version 5.0.0: done (#95).
-   of the 5.0.0 section to the release date (fold the `[Unreleased]` entries
-   into it), tag `5.0.0` (no `v` prefix), build in Release, and clean
-   `C:\Program Files\WindowsPowerShell\Modules\NTFSSecurity` before
-   `Publish-Module`; releases so far were Debug builds published with the
-   whole output folder (`.pdb`, `.xml`, `System.Management.Automation.dll`),
-   and the removed `NTFSSecurity-Help.xml` would ship again.
 4b. CI and the wiki on GitHub Actions: done (#96). Left to the maintainer:
    revoke AppVeyor's GitHub access if it is still granted, consider
    **Restrict editing to collaborators only** for the wiki, and optionally
    ask `Sup3rlativ3` to delete the Read the Docs project.
-4c. Version history from the PowerShell Gallery: PR-ready on
+4c. Version history from the PowerShell Gallery: done (#97).
-   `ai/version-history`.
+4d. Release 5.0.0 through CI (Decision 12): PR-ready on `ai/release-5.0.0`.
+   Before the first tag, the maintainer creates the Gallery API key, the
+   environment `powershell-gallery`, and its secret `PSGALLERY_API_KEY`
+   (steps in `Docs/Contributing/05-Releasing.md`). Then: merge, tag
+   `5.0.0-rc1`, test the prerelease, check its Gallery tags and
+   `Find-Command`, and for the final release remove the label and date the
+   changelog section. Releases no longer come from a local build, so the
+   old manual steps (cleaning
+   `C:\Program Files\WindowsPowerShell\Modules\NTFSSecurity`, Debug
+   builds) no longer apply.
 5. Code defects, listed below: `review: on`, one PR per group, regression
    test first. Pester 5 tests import `NTFSSecurity\bin\Release`, run in a
    `$env:TEMP` sandbox and in the CI workflow (pattern:

.memory-bank/systemPatterns.md

@@ -58,6 +58,7 @@ Each Decision record is a file in `decisions/`; read only the relevant ones.
 | 9 | [Keep the documentation on GitHub](decisions/0009-docs-on-github.md) |
 | 10 | [One version for the manifest, assemblies, and changelog](decisions/0010-one-version.md) |
 | 11 | [CI and the wiki run on GitHub Actions](decisions/0011-github-actions.md) |
+| 12 | [Releases are built and published by CI on a version tag](decisions/0012-ci-releases.md) |
 
 ## Patterns
 
@@ -96,6 +97,10 @@ Each Decision record is a file in `decisions/`; read only the relevant ones.
   failed tests go to the job summary, the NUnit file to the `test-results`
   artifact, and it fails on failed test files too (`Result -ne 'Passed'`).
 - `Tests\Manifest.Tests.ps1` checks the built manifest: `Test-ModuleManifest`
-  without errors or warnings, exactly 36 cmdlets, and one version
+  without errors or warnings, exactly 36 cmdlets, and the same version in
-  (Decision 10). Add a new cmdlet to `CmdletsToExport` and to the expected
+  the manifest and the assemblies (Decision 10). Add a new cmdlet to
-  count in the same change.
+  `CmdletsToExport` and to the expected count in the same change.
+- `Tests\Release.Tests.ps1` checks that `CHANGELOG.md` has release notes
+  for the manifest version (dated section, or `[Unreleased]` for a
+  prerelease) and the packages: only `FileList` files, version with label,
+  command tags, and `NTFSSecurity.zip` with the module folder.

.memory-bank/techContext.md

@@ -66,9 +66,11 @@ source: repository evidence
 ## Constraints
 
 - `ModuleVersion` on `master` is `5.0.0` (not released); the latest tag and
-  Gallery release is `4.2.6`. The manifest requires PowerShell 5.1 and .NET
+  Gallery release is `4.2.6`. On `ai/release-5.0.0`, the manifest adds the
-  Framework 4.5.2, uses `RootModule`, and lists exactly 36 cmdlets;
+  prerelease label `rc1`, so the next tag is `5.0.0-rc1`. The manifest
-  `Test-ModuleManifest` passes in Windows PowerShell 5.1 and PowerShell 7.6.
+  requires PowerShell 5.1 and .NET Framework 4.5.2, uses `RootModule`, and
+  lists exactly 36 cmdlets; `Test-ModuleManifest` passes in Windows
+  PowerShell 5.1 and PowerShell 7.6.
 - Besides the shipped help file and its tests (#93), the module source at
   `master` differs from tag `4.2.6` by the `Remove-Item2 -PassThur` to
   `-PassThru` rename (with a `-PassThur` alias), the manifest changes of
@@ -78,12 +80,12 @@ source: repository evidence
   4.2.6 (2019-07-12); none has release notes. Older versions were released
   on CodePlex only, and their dates are lost. The git history starts on
   2016-10-10, when the project moved from CodePlex.
-- Releases have no script and no CI deployment. Evidence from 4.2.6: the
+- Releases up to 4.2.6 had no script and no CI deployment: the Gallery
-  Gallery DLLs are Debug builds (`DebuggableAttribute` 263), the nuspec
+  DLLs are Debug builds (`DebuggableAttribute` 263), the nuspec comes from
-  comes from `Publish-Module`, the package holds the whole output folder
+  `Publish-Module`, the package holds the whole output folder (`.pdb`,
-  (`.pdb`, `AlphaFS.xml`, 7 MB `System.Management.Automation.dll`), and the
+  `AlphaFS.xml`, 7 MB `System.Management.Automation.dll`), and tags carry
-  published manifest differs from the tag only by `ModuleVersion` (tags
+  the previous version. From 5.0.0 on, CI publishes on a version tag
-  carry the previous version). GitHub releases attach `NTFSSecurity.zip`.
+  (Decision 12). GitHub releases attach `NTFSSecurity.zip`.
 - CI: GitHub Actions on pull requests and pushes to `master` (Decision 11).
   AppVeyor no longer reports on `master` (checked on `4f9f7cc`). The Read
   the Docs project `ntfssecurity` (maintainer `Sup3rlativ3`) and a second
@@ -118,8 +120,17 @@ source: repository evidence
   Windows PowerShell 5.1 and in PowerShell 7. Job `wiki` on `ubuntu-latest`
   clones the wiki (`gh auth setup-git` with the built-in token), runs
   `Export-WikiContent.ps1`, lists the changed pages in the job summary, and
-  publishes from `master` only. Actions are pinned by commit SHA:
+  publishes from `master` only. After the tests, `build` runs
-  `actions/checkout` v7.0.1, `actions/upload-artifact` v7.0.1.
+  `New-ModulePackage.ps1` and uploads the artifact `packages` (nupkg and
+  `NTFSSecurity.zip`). Job `release` runs only for tags matching
+  `[0-9]+.[0-9]+.[0-9]+` or `[0-9]+.[0-9]+.[0-9]+-*`, in the environment
+  `powershell-gallery` (secret `PSGALLERY_API_KEY`); see Decision 12.
+  Actions are pinned by commit SHA: `actions/checkout` v7.0.1,
+  `actions/upload-artifact` v7.0.1, `actions/download-artifact` v8.0.1.
+- Packaging needs PSResourceGet (`Compress-PSResource`, PowerShell 7.4 or
+  later); its tests skip in Windows PowerShell. Dry run locally: run
+  `New-ModulePackage.ps1` against `NTFSSecurity\bin\Release` into
+  `$env:TEMP`, then extract the nupkg into a folder and import it there.
 - Read CI runs with `gh run list --repo raandree/NTFSSecurity --workflow
   ci.yml`, `gh pr checks <number>`, and `gh run view <id> --log-failed`
   (read-only).