Browse Source

chore(memory-bank): record the docs on GitHub and the version decisions

- Decision 9: keep the documentation on GitHub; no Read the Docs site,
  and the wiki is retired. Decision 4 now rests on it.
- Work package 3 redefined and PR-ready; work package 4 decisions:
  PowerShellVersion 5.1, DotNetFrameworkVersion 4.5.2, RootModule, and
  5.0.0 with the PassThur alias.
- Correct the Windows PowerShell 5.1 recipe (don't clear PSModulePath),
  and record the local build from the NuGet cache, the link-check
  limits, and the deleted fork behind the Read the Docs project.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
pull/94/head
Raimund Andree 1 week ago
parent
commit
1d370d96db
  1. 39
      .memory-bank/activeContext.md
  2. 7
      .memory-bank/decisions/0004-online-help-on-github.md
  3. 25
      .memory-bank/decisions/0009-docs-on-github.md
  4. 68
      .memory-bank/progress.md
  5. 10
      .memory-bank/projectbrief.md
  6. 7
      .memory-bank/systemPatterns.md
  7. 48
      .memory-bank/techContext.md

39
.memory-bank/activeContext.md

@ -1,6 +1,6 @@
---
status: current
last-verified: 2026-10-02
last-verified: 2026-10-04
owner: active-agent
source: current task evidence
---
@ -9,26 +9,29 @@ source: current task evidence
## Current focus
Work packages 1 (#92) and 2 (#93) are merged. Next is work package 3 (Read
the Docs), after the maintainer's go-ahead, on the local branch
`ai/read-the-docs`, which so far carries Memory Bank notes only. The
remaining packages and their details are in `progress.md`.
Work package 3 was redefined by the maintainer: no Read the Docs, the docs
stay on GitHub, and the wiki is retired (Decision 9). It is PR-ready on the
local branch `ai/docs-on-github` (`84328dc` plus Memory Bank notes). Work
package 4 (manifest and version) continues next, stacked on it, with the
maintainer's decisions recorded in `progress.md`.
## Evidence
- #92 was merged with a merge commit (`d917832`) and #93 squash-merged
(`14799fb`); the tree of `master` equals the tested `c9fbaf5`.
- AppVeyor: the PR build of #93 (54834295) and the `master` build of
`14799fb` (54834350) each passed 218 of 218 Pester tests, listed once
each on the Tests tab; the `master` build of `d917832` passed too.
- The remote branches `ai/housekeeping` and `ai/ship-help` are deleted, and
so are the local ones. The only unmerged commit, the remote-mutation note
(`9dc2022`), is now `023506c` on `ai/read-the-docs`.
- The agent can't push or open PRs (`techContext.md`, Constraints): it
prepares the commands and PR descriptions, and the maintainer runs them.
- All 256 relative links in `Docs`, `README.md`, and `CHANGELOG.md` resolve,
including 5 anchors checked against GitHub's slug rules; MarkdownLinkCheck
0.2.0 (CI step 02) finds 0 broken links in `Docs` in Windows PowerShell
5.1; markdownlint reports 0 issues in the changed pages.
- The documented manual install (`Unblock-File`, `Expand-Archive` into
`$env:ProgramFiles\WindowsPowerShell\Modules`) was tested with the 4.2.6
zip in a `$env:TEMP` sandbox: the module imports under `RemoteSigned`.
`Expand-Archive` doesn't pass the download mark on; File Explorer's zip
handler does, and the import then fails.
- The wiki stopped at 4.2.4; the Gallery has 4.2.5 (2019-07-11) and 4.2.6
(2019-07-12), whose notes were reconstructed from `4.2.4..4.2.6`.
- 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
Wait for the maintainer's go-ahead for work package 3. Nothing on
`ai/read-the-docs` needs pushing before then; its Memory Bank commits go
into the work package 3 PR.
Ask which assemblies follow the module version, then implement work
package 4 test-first on a branch stacked on `ai/docs-on-github`.

7
.memory-bank/decisions/0004-online-help-on-github.md

@ -1,7 +1,7 @@
---
status: accepted
date: 2026-10-02
last-verified: 2026-10-02
last-verified: 2026-10-04
owner: shared
source: PR #91 (moved from systemPatterns.md)
---
@ -10,5 +10,6 @@ source: PR #91 (moved from systemPatterns.md)
- Choice: `online version` of every cmdlet page is
`https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/<Name>.md`.
- Rationale: The Read the Docs project builds a stale fork, so its URLs show
outdated pages; GitHub always shows `master`.
- Rationale: GitHub renders the docs of `master`, and there is no other
documentation site (Decision 9). Originally chosen because the Read the
Docs project built a stale fork.

25
.memory-bank/decisions/0009-docs-on-github.md

@ -0,0 +1,25 @@
---
status: accepted
date: 2026-10-04
last-verified: 2026-10-04
owner: shared
source: maintainer decision in work package 3
---
# Decision 9: Keep the documentation on GitHub
- Choice: The documentation lives in `Docs` and `README.md`, and GitHub
renders it. There is no documentation site: the Read the Docs and MkDocs
configuration is removed. The GitHub wiki is retired: its version history
and installation steps moved to `Docs/Version-History.md` and
`Docs/README.md`, and the maintainer turns the wiki off.
- Rationale: One source of truth that is versioned with the code, reviewed
in pull requests, and checked by AppVeyor. The Read the Docs project
`ntfssecurity` belongs to `Sup3rlativ3` and points to a fork that no
longer exists; a wiki is edited outside pull requests and CI.
- Consequences: `online version` links stay on GitHub (Decision 4). Section
anchors follow GitHub's rules. `Docs/index.md` became `Docs/README.md`, so
that GitHub shows it when you open the `Docs` folder.
- Rejected: taking over or re-importing the Read the Docs project with a
strict MkDocs build (prepared on the local branch `ai/read-the-docs`, not
merged), and publishing `Docs` to the wiki.

68
.memory-bank/progress.md

@ -1,6 +1,6 @@
---
status: current
last-verified: 2026-10-02
last-verified: 2026-10-04
owner: active-agent
source: repository evidence
---
@ -34,6 +34,10 @@ from the 4.2.6 release only by the `Remove-Item2 -PassThru` rename and
upload had listed 870), six cmdlet-page links reworded for the help
text. AppVeyor passed 218 of 218 on the PR (54834295) and on `master`
(54834350).
- 2026-10-04: The maintainer dropped Read the Docs: the docs stay on GitHub
and the wiki is retired (Decision 9). Work package 3 committed locally on
`ai/docs-on-github` (`84328dc`). The strict Read the Docs build prepared
before stays unmerged on the local branch `ai/read-the-docs`.
## Stable capabilities
@ -52,39 +56,35 @@ next package starts only after the maintainer's go-ahead.
1. Housekeeping: done (#92).
2. Ship help: done (#93).
3. Read the Docs, next. The local branch `ai/read-the-docs` exists and so
far carries Memory Bank notes only. The project `ntfssecurity`
(`https://app.readthedocs.org/projects/ntfssecurity/`) is maintained by
GitHub user `Sup3rlativ3` and builds the fork `Sup3rlativ3/NTFSSecurity`
(last build about 2021); the repository side is ready
(`.readthedocs.yml`, `Docs/requirements.txt`). The switch happens in the
Read the Docs dashboard. Give the maintainer exact steps for both
options: (a) `Sup3rlativ3` adds him as maintainer and changes the
repository URL, or (b) he imports `raandree/NTFSSecurity` as a new
project (the slug `ntfssecurity` is taken). Ask before installing Python
for `mkdocs build --strict`. After the switch, confirm a build of
`master`, propose whether the `online version` links move to Read the
Docs (Decision 4), and add a documentation link to `README.md`. Done
when Read the Docs builds `master` of this repository and shows the
current pages.
4. Manifest and version: remove `Show-NTFSSimpleAccess` and the duplicate
inheritance entries from `CmdletsToExport` (exactly 36 cmdlets
exported). Versions disagree: manifest 4.2.5, tag and Gallery 4.2.6,
`AssemblyVersion` 4.2.1.0. Propose the next SemVer version with and
without `[Alias('PassThur')]` on `Remove-Item2 -PassThru` (the rename in
#64 is breaking), plus `PowerShellVersion` and `DotNetFrameworkVersion`
(manifest 2.0 and 3.5; the assemblies target .NET Framework 4.5.2), and
ask. Move the `[Unreleased]` entries into the new version section (ask
whether the build-only "Read the Docs build configuration" entry stays,
Decision 7) and align `AssemblyInfo`. No tag or publish. Done when
`Test-ModuleManifest` passes, 36 cmdlets are exported, and CI is green.
Inputs: `Test-ModuleManifest` already fails on
`PowerShellVersion = '2.0'` with `CompatiblePSEditions`; releases are
Debug builds published with the whole output folder (`.pdb`, `.xml`,
`System.Management.Automation.dll`), which `FileList` doesn't list.
Before the next build and `Publish-Module`, clean
`C:\Program Files\WindowsPowerShell\Modules\NTFSSecurity`, or the removed
`NTFSSecurity-Help.xml` ships again.
3. Docs on GitHub (was: Read the Docs), PR-ready on `ai/docs-on-github`:
Read the Docs and MkDocs configuration removed, `Docs/index.md` renamed
to `Docs/README.md`, the wiki's version history and install steps moved
into `Docs` (with reconstructed notes for 4.2.5 and 4.2.6), contributor
guide updated. After the merge, the maintainer turns the wiki off, points
the notes of releases 4.2.4 and 4.2.6 to `Docs/Version-History.md`, and
may ask `Sup3rlativ3` to delete the Read the Docs project.
4. Manifest and version, in progress, stacked on `ai/docs-on-github`.
Maintainer decisions: `PowerShellVersion` 5.1, `DotNetFrameworkVersion`
4.5.2, `RootModule` instead of `ModuleToProcess`; version 5.0.0 with
`[Alias('PassThur')]` on `Remove-Item2 -PassThru` (the changelog lists
`-PassThur` under Deprecated); the changelog entry about the
documentation site is gone (work package 3). Open: which assemblies
follow the module version. Remove `Show-NTFSSimpleAccess` and the
duplicate inheritance entries from `CmdletsToExport` (exactly 36
cmdlets exported), move the `[Unreleased]` entries into the 5.0.0
section, and align `AssemblyInfo`. No tag or publish. Done when
`Test-ModuleManifest` passes in Windows PowerShell 5.1 and PowerShell 7,
36 cmdlets are exported, the versions agree, and CI is green.
Baseline: `Test-ModuleManifest` fails in both editions
(`CompatiblePSEditions` needs `PowerShellVersion` 5.1) and warns about
`ModuleToProcess`; 41 `CmdletsToExport` entries, 37 unique; versions:
manifest 4.2.5, `NTFSSecurity` 4.2.1.0, `Security2` 3.2.3.0,
`PrivilegeControl` 1.0.0.0, `ProcessPrivileges` 1.5.7.0 (vendored);
`Log` isn't shipped. Releases are Debug builds published with the whole
output folder (`.pdb`, `.xml`, `System.Management.Automation.dll`), which
`FileList` doesn't list. Before the next build and `Publish-Module`,
clean `C:\Program Files\WindowsPowerShell\Modules\NTFSSecurity`, or the
removed `NTFSSecurity-Help.xml` ships again.
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 `appveyor.yml` (pattern:

10
.memory-bank/projectbrief.md

@ -19,8 +19,9 @@ Source: `README.md`, `NTFSSecurity/NTFSSecurity.psd1`.
## Scope
- In scope: module source (`NTFSSecurity`, `Security2`, `PrivilegeControl`,
`ProcessPrivileges`), module manifest and type/format data, the MkDocs
documentation site in `Docs/`, and `README.md`.
`ProcessPrivileges`), module manifest and type/format data, the
documentation in `Docs/` (rendered by GitHub, Decision 9), and
`README.md`.
- Out of scope: registry security. `Security2/Registry/RegistrySecurity.cs`
exists, but no registry cmdlet is exported.
- Distribution: PowerShell Gallery package `NTFSSecurity` and GitHub releases.
@ -28,8 +29,9 @@ Source: `README.md`, `NTFSSecurity/NTFSSecurity.psd1`.
## Stakeholders
- Maintainer and author: Raimund Andree (`raandree`), per the manifest.
- Documentation contributors: James Smith (`mkdocs.yml` `site_author`);
the AppVeyor documentation build runs under the `Sup3rlativ3` account.
- Documentation contributors: James Smith (`site_author` in the former
`mkdocs.yml`) and `Sup3rlativ3` (#62), who owns the Read the Docs project
`ntfssecurity` and a second AppVeyor project.
- End users: To confirm beyond the README summary.
## Acceptance criteria

7
.memory-bank/systemPatterns.md

@ -1,6 +1,6 @@
---
status: current
last-verified: 2026-10-02
last-verified: 2026-10-04
owner: active-agent
source: repository evidence
---
@ -55,6 +55,7 @@ Each Decision record is a file in `decisions/`; read only the relevant ones.
| 6 | [CI checks the docs against a build of the source](decisions/0006-ci-checks-docs-against-build.md) |
| 7 | [CHANGELOG lists user-visible changes only](decisions/0007-changelog-user-visible-only.md) |
| 8 | [Commit the generated help file and check it in CI](decisions/0008-commit-generated-help.md) |
| 9 | [Keep the documentation on GitHub](decisions/0009-docs-on-github.md) |
## Patterns
@ -62,6 +63,10 @@ Each Decision record is a file in `decisions/`; read only the relevant ones.
- Run platyPS in Windows PowerShell 5.1 against a module build; a copy of
`Docs/Cmdlets` must round-trip through `Update-MarkdownHelp` unchanged.
- GitHub renders the docs (Decision 9). AppVeyor's link check covers only
relative links in `Docs` and ignores anchors, so check anchors against
GitHub's slug rules (lowercase, punctuation removed, spaces to hyphens)
and the links in `README.md` and `CHANGELOG.md` separately.
- platyPS rewrites non-ASCII punctuation such as em dashes; keep cmdlet pages
ASCII-only.
- In cmdlet pages, end a sentence with a link: platyPS renders a link as

48
.memory-bank/techContext.md

@ -1,6 +1,6 @@
---
status: current
last-verified: 2026-10-02
last-verified: 2026-10-04
owner: active-agent
source: repository evidence
---
@ -19,8 +19,8 @@ source: repository evidence
- Module: `NTFSSecurity.psd1` loads `NTFSSecurity.psm1` (aliases `dir2`,
`gi2`, `rm2`, `del2`), `NTFSSecurity.Init.ps1` (Add-Type of the helper
assemblies, prepends `NTFSSecurity.format.ps1xml`), and `NTFSSecurity.dll`.
- Documentation: MkDocs (`mkdocs.yml`, theme `readthedocs`, `docs_dir: ./Docs`)
built by Read the Docs (`.readthedocs.yml` v2); cmdlet pages are platyPS
- Documentation: Markdown in `Docs` and `README.md`, rendered by GitHub; no
documentation site and no wiki (Decision 9). Cmdlet pages are platyPS
0.14 markdown (schema 2.0.0) in `Docs/Cmdlets`.
- Help: `NTFSSecurity\en-US\NTFSSecurity.dll-Help.xml`, generated from
`Docs/Cmdlets` and committed (Decision 8).
@ -39,11 +39,25 @@ source: repository evidence
package; the legacy C# 5 compiler fails with CS0136. `dotnet msbuild`
fails on the binary resources in `Resources.resx` (MSB3822, MSB3823).
- platyPS 0.14.2, Pester 5.7.1, PSScriptAnalyzer, and powershell-yaml are
installed only for PowerShell 7. Windows PowerShell 5.1 imports platyPS
and Pester by full path
installed only for PowerShell 7. Windows PowerShell 5.1, started from
PowerShell 7, imports platyPS and Pester by full path
(`~\OneDrive\Documents\PowerShell\Modules\platyPS\0.14.2`,
`C:\Program Files\PowerShell\Modules\Pester\5.7.1`) with
`$env:PSModulePath` cleared. MarkdownLinkCheck is not installed.
`C:\Program Files\PowerShell\Modules\Pester\5.7.1`). Leave
`$env:PSModulePath` alone: PowerShell 7 hands the child the Windows
PowerShell default path, and clearing it leaves Windows PowerShell without
its core modules (Pester fails: `Add-Member` not found).
- MarkdownLinkCheck is not installed, and `Save-Module` crashed (FailFast)
in PowerShell 7.6 on 2026-10-04. Download the 0.2.0 package from
`https://www.powershellgallery.com/api/v2/package/MarkdownLinkCheck/0.2.0`
into `$env:TEMP`, extract it, and import it by path.
- The workstation is ARM64; PowerShell 7 runs as x64 under emulation.
Python 3.12.10 (ARM64) is installed per user with winget, the
maintainer's choice for an MkDocs check that Decision 9 made unnecessary.
- The NuGet cache (`~\.nuget\packages`) holds every build dependency: copy
`alphafs\2.2.1`, `system.management.automation.dll\10.0.10586`, and
`microsoft.netframework.referenceassemblies.net452\1.0.3` into
`packages\<Id>.<Version>`, and point `CscToolPath` at
`microsoft.net.compilers\4.2.0\tools`.
## Constraints
@ -64,8 +78,11 @@ source: repository evidence
published manifest differs from the tag only by `ModuleVersion` (tags
carry the previous version). GitHub releases attach `NTFSSecurity.zip`.
- CI: AppVeyor project `raandree/ntfssecurity` builds branches and pull
requests. Read the Docs (`ntfssecurity`) and a second AppVeyor project are
attached to the fork `Sup3rlativ3/NTFSSecurity`.
requests. The Read the Docs project `ntfssecurity` (maintainer
`Sup3rlativ3`) and a second AppVeyor project are attached to the fork
`Sup3rlativ3/NTFSSecurity`, which no longer exists (GitHub 404,
2026-10-04). That site still serves pages from 2020 and isn't used
(Decision 9).
- `Get-FileHash2` fails in PowerShell 7; all other cmdlets passed a smoke
test in PowerShell 7.6.
- `CHANGELOG.md` lists user-visible changes only; CI and build-only changes
@ -103,10 +120,13 @@ source: repository evidence
- Help file: `New-ExternalHelp -Path .\Docs\Cmdlets -OutputPath
.\NTFSSecurity\en-US -Force` must leave `git status` unchanged.
- Pester: run detached (`Start-DetachedPowerShell.ps1`) in Windows
PowerShell 5.1; a run without `bin\Release\en-US` must fail.
PowerShell 5.1: the launcher starts `pwsh`, and its payload runs
`powershell.exe -NoProfile -EncodedCommand` with Pester imported by full
path. A run without `bin\Release\en-US` must fail.
- Markdown lint: `npx markdownlint-cli2` with `MD013` limited to prose
(tables, code, and headings excluded) on the conceptual pages.
- YAML: `ConvertFrom-Yaml` (powershell-yaml) on `mkdocs.yml`,
`.readthedocs.yml`, and `appveyor.yml`; every `nav` target must exist.
- MkDocs needs Python, which this workstation does not have; `mkdocs build
--strict` was not run.
- YAML: `ConvertFrom-Yaml` (powershell-yaml) on `appveyor.yml`.
- Links: AppVeyor step 02 (MarkdownLinkCheck 0.2.0) checks only relative
links in `Docs`; it strips anchors and skips absolute URLs. Check anchors
against GitHub's heading slugs, and the links in `README.md` and
`CHANGELOG.md`, with a script.

Loading…
Cancel
Save