Merge pull request #92 from raandree/ai/housekeeping

chore: ignore prompt history and record changelog policy

.gitignore

@@ -243,3 +243,6 @@ ModelManifest.xml
 
 # FAKE - F# Make
 .fake/
+
+# Memory Bank: local prompt history, not version-controlled
+/.memory-bank/promptHistory.md

.memory-bank/activeContext.md

@@ -9,22 +9,23 @@ source: current task evidence
 
 ## Current focus
 
-PR #91 (`ai/docs-alignment`): CI fixed by building the module from source
-in `appveyor.yml` and checking the docs against that build.
+Work package 1 (housekeeping) on branch `ai/housekeeping`; the five work
+packages and their order are in `progress.md`.
 
 ## Evidence
 
-- AppVeyor build 54825990 failed in step 01: `Update-MarkdownHelp` against
-  the Gallery module 4.2.6 rewrote `Remove-Item2 -PassThru` to `-PassThur`.
-- Against a Release build of the source, `Update-MarkdownHelp` changes none
-  of the 36 pages; a simulation of all `appveyor.yml` steps in a fresh clone
-  passed, and a page with stale syntax made it fail as intended.
-- The link check (`Get-MarkdownLink -BrokenOnly`) finds 308 links, none
-  broken.
+- PR #91 is merged into `master` as `690d8dd` (squash merge). The local
+  branch `ai/docs-alignment` had the same tree as `690d8dd` and is deleted;
+  GitHub had already deleted the remote branch.
+- `.memory-bank/promptHistory.md` is ignored by git (`.gitignore`) and stays
+  a local file.
+- The changelog policy is Decision 7. The inline Decisions moved to
+  `decisions/` records because `systemPatterns.md` was near its 110-line
+  budget.
 - Read the Docs project `ntfssecurity` still builds the fork
   `Sup3rlativ3/NTFSSecurity`.
 
 ## Next step
 
-PR #91 is green (AppVeyor 54828078 branch and 54828080 pull request, both
-on `dbd8d16`). Await review and merge; open follow-ups are in `progress.md`.
+The maintainer pushes `ai/housekeeping` and opens the PR. After the
+go-ahead, start work package 2 (ship the generated help).

.memory-bank/decisions/0001-canonical-memory-bank.md

@@ -0,0 +1,12 @@
+---
+status: accepted
+date: 2026-10-02
+last-verified: 2026-10-02
+owner: shared
+source: PR #91 (moved from systemPatterns.md)
+---
+
+# Decision 1: Use the canonical Memory Bank base
+
+- Choice: Keep durable project context in .memory-bank.
+- Rationale: Preserve evidence-backed context across sessions.

.memory-bank/decisions/0002-platyps-cmdlet-reference.md

@@ -0,0 +1,15 @@
+---
+status: accepted
+date: 2026-10-02
+last-verified: 2026-10-02
+owner: shared
+source: PR #91 (moved from systemPatterns.md)
+---
+
+# Decision 2: Cmdlet reference stays platyPS markdown
+
+- Choice: `Docs/Cmdlets/*.md` keep the platyPS 0.14 schema 2.0.0 layout
+  (upper-case section headings, YAML parameter blocks, one paragraph per
+  line) so `Update-MarkdownHelp` and `New-ExternalHelp` round-trip.
+- Rationale: `appveyor.yml` checks the pages with `Update-MarkdownHelp`;
+  the same files can generate MAML help.

.memory-bank/decisions/0003-document-source-at-head.md

@@ -0,0 +1,14 @@
+---
+status: accepted
+date: 2026-10-02
+last-verified: 2026-10-02
+owner: shared
+source: PR #91 (moved from systemPatterns.md)
+---
+
+# Decision 3: Document the source at HEAD
+
+- Choice: Docs describe the code on `master`. Where HEAD differs from the
+  latest Gallery release, the page says which version changed.
+- Rationale: The user asked to align docs with the actual code; the only
+  current difference is `Remove-Item2 -PassThru` (4.2.6 spells `-PassThur`).

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

@@ -0,0 +1,14 @@
+---
+status: accepted
+date: 2026-10-02
+last-verified: 2026-10-02
+owner: shared
+source: PR #91 (moved from systemPatterns.md)
+---
+
+# Decision 4: Online help points to GitHub
+
+- 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`.

.memory-bank/decisions/0005-document-defects-separately.md

@@ -0,0 +1,15 @@
+---
+status: accepted
+date: 2026-10-02
+last-verified: 2026-10-02
+owner: shared
+source: PR #91 (moved from systemPatterns.md)
+---
+
+# Decision 5: Document defects, don't fix them in docs work
+
+- Choice: Code defects found while documenting are described on the affected
+  page (workaround or limitation) and listed in `progress.md`; source code is
+  changed only in separate, tested work.
+- Rationale: No build toolchain was available to verify code changes, and
+  the docs must describe current behavior.

.memory-bank/decisions/0006-ci-checks-docs-against-build.md

@@ -0,0 +1,16 @@
+---
+status: accepted
+date: 2026-10-02
+last-verified: 2026-10-02
+owner: shared
+source: PR #91 (moved from systemPatterns.md)
+---
+
+# Decision 6: CI checks the docs against a build of the source
+
+- Choice: `appveyor.yml` builds `NTFSSecurity.csproj` and runs
+  `Update-MarkdownHelp` against `NTFSSecurity\bin\Release`, not against the
+  module from the PowerShell Gallery.
+- Rationale: Checking against the last release fails for every unreleased
+  parameter change (PR #91 failed on `Remove-Item2 -PassThru`) and never
+  compiled the code.

.memory-bank/decisions/0007-changelog-user-visible-only.md

@@ -0,0 +1,17 @@
+---
+status: accepted
+date: 2026-10-02
+last-verified: 2026-10-02
+owner: shared
+source: maintainer decision after PR #91
+---
+
+# Decision 7: CHANGELOG lists user-visible changes only
+
+- Choice: `CHANGELOG.md` lists only changes that module users or
+  documentation readers can notice. CI and build-only changes, such as
+  `appveyor.yml` or local build tooling, get no entry.
+- Rationale: Agreed with the maintainer. It follows Keep a Changelog: the
+  file tells users what changed, and git history covers CI and build work.
+- Example: PR #91 lists the documentation rewrite but not the switch of
+  `appveyor.yml` to building the module from source.

.memory-bank/progress.md

@@ -9,9 +9,9 @@ source: repository evidence
 
 ## Current status
 
-Documentation matches the cmdlets at HEAD. The module source is unchanged
-since the 4.2.6 release except the `Remove-Item2 -PassThru` rename and
-`CompatiblePSEditions`.
+PR #91 is merged: documentation matches the cmdlets at HEAD. The module
+source is unchanged since the 4.2.6 release except the
+`Remove-Item2 -PassThru` rename and `CompatiblePSEditions`.
 
 ## Recent milestones
 
@@ -24,6 +24,16 @@ since the 4.2.6 release except the `Remove-Item2 -PassThru` rename and
 - 2026-10-02: PR #91 build fixed: `appveyor.yml` builds the module from
   source and checks the docs against that build instead of the Gallery
   release (root cause of the `Remove-Item2 -PassThru` drift failure).
+- 2026-10-02: PR #91 merged into `master` as `690d8dd` (squash merge);
+  branch `ai/docs-alignment` deleted locally and on GitHub.
+- 2026-10-02: Work package 1 (housekeeping, `ai/housekeeping`): local
+  `promptHistory.md` ignored by git; changelog policy recorded as
+  Decision 7; Decisions moved from `systemPatterns.md` to `decisions/`.
+- 2026-10-02: PR #83 (TechNet tutorial links) reviewed and found
+  superseded: #91 ships the same two `learn.microsoft.com` links in
+  `Docs/index.md` and `README.md`. The maintainer decided to close it;
+  the remote-mutation hook denied the agent's `gh pr close`, so the
+  maintainer closes it by hand.
 
 ## Stable capabilities
 
@@ -35,19 +45,104 @@ since the 4.2.6 release except the `Remove-Item2 -PassThru` rename and
 
 ## Open work
 
-- Ship help: add the generated `en-US\NTFSSecurity.dll-Help.xml` to the
-  build and drop the stale `NTFSSecurity-Help.xml`.
-- Publishing: re-point Read the Docs from the fork `Sup3rlativ3/NTFSSecurity`
-  to this repository (or create a new Read the Docs project).
-- Manifest: remove `Show-NTFSSimpleAccess` and duplicates from
-  `CmdletsToExport`; bump `ModuleVersion` (4.2.5 in source, 4.2.6 released).
-- Code defects found while documenting (each documented on its page):
-  `Add-NTFSAudit` duplicate position 2; SD parameter sets of
-  `Add/Remove-NTFSAccess/Audit` need `-AppliesTo`; `Set-NTFSInheritance`
-  nullable crash and hard-coded removal; inheritance cmdlets ignore
-  `EnablePrivileges = $false`; `Get-NTFSEffectiveAccess`
-  `-ExcludeNoneAccessEntries` and SD set ineffective; `-Account`/SD ignored by
-  `Get-NTFSOrphanedAccess/Audit` and `Get-NTFSSimpleAccess`; `Copy-Item2`
-  fails on folders with files; `Get-ChildItem2` throws on a file path;
-  `return` instead of `continue` in several `ProcessRecord` loops; wrong
-  `OutputType` on several cmdlets; `Get-FileHash2` in PowerShell 7.
+Work packages in the order agreed with the maintainer. Each gets one
+`ai/<slug>` branch and PR, committed locally; the maintainer pushes, and
+the next package starts only after the maintainer's go-ahead.
+
+1. Housekeeping: committed on `ai/housekeeping`; awaiting push and PR.
+2. Ship help: generate `en-US\NTFSSecurity.dll-Help.xml` from `Docs/Cmdlets`
+   with `New-ExternalHelp` and ship it (csproj `Content`, manifest
+   `FileList`); remove the stale `NTFSSecurity-Help.xml` and, if unused,
+   `NTFSSecurity\Help\NTFSSecurity.Help.pshproj`. Ask the maintainer:
+   commit the file plus a CI currency check, or generate it in the build.
+3. Read the Docs: project `ntfssecurity` (maintainer `Sup3rlativ3`) builds
+   the fork; switch it to this repository or import a new project. Ask
+   before installing Python for `mkdocs build --strict`.
+4. Manifest and version: remove `Show-NTFSSimpleAccess` and the duplicate
+   inheritance entries from `CmdletsToExport` (36 cmdlets remain); ask
+   about the next version (with or without a `PassThur` alias),
+   `PowerShellVersion`, and `DotNetFrameworkVersion`; align `AssemblyInfo`.
+   No tag or publish.
+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`, and skip elevated cases when
+   not elevated. Each fix updates its cmdlet page and `CHANGELOG.md`.
+
+### Code defects (work package 5)
+
+Numbered as agreed with the maintainer; each is documented on its page.
+
+#### A: Crashes and wrong results
+
+- (1) `Set-NTFSInheritance` reads an unset `Nullable<bool>` when
+  `-AccessInheritanceEnabled` is omitted; omitted should mean unchanged.
+- (2) `Get-ChildItem2` casts a file `-Path` to `DirectoryInfo`
+  (`InvalidCastException`).
+- (3) `Get-FileHash2` returns at a folder in `-Path` and skips the rest.
+- (4) `Get-NTFSAudit` re-emits the previous item's entries after a failed
+  path, and returns nothing without the Security privilege instead of an
+  error.
+- (5) `Add-NTFSAudit`: `-Account` and `-AccessRights` share position 2;
+  use 2 and 3 like `Remove-NTFSAudit`.
+- (6) `-PassThru` returns access entries in `Add-NTFSAudit` SD sets and
+  `Remove-NTFSAudit` Path sets.
+- (7) `FileSystemAuditRule2.GetFileSystemAuditRules` takes
+  `InheritanceEnabled` from `AreAccessRulesProtected`.
+- (8) `Get-NTFSInheritance -SecurityDescriptor` reports
+  `AuditInheritanceEnabled = $true` without a SACL (Path set: `$null`).
+- (9) `Get-NTFSOwner`: the access-denied retry repeats the failing call,
+  and the catch-all turns `PipelineStoppedException` into
+  `ReadSecurityError`.
+- (10) `Copy-Item2` fails on a folder with files
+  (`DirectoryNotFoundException`).
+- (11) `Disable-Privileges` hits a null `privileges` field when
+  `EnablePrivileges = $false`.
+- (12) The six inheritance cmdlets enable privileges unconditionally in
+  `BeginProcessing` and leave them enabled.
+- (13) Format view `Children2`: the `Inherits` column uses
+  `IsInheritanceBlocked`, so it always shows `True` for `Get-ChildItem2`.
+
+#### B: Ignored parameters and parameter sets
+
+- (14) SD sets of `Add-/Remove-NTFSAccess` and `Add-/Remove-NTFSAudit`
+  cannot resolve without `-AppliesTo` or the flag parameters.
+- (15) `Get-NTFSEffectiveAccess`: `-ExcludeNoneAccessEntries` has no
+  effect, there is no output without `-Path`, and the SD set returns
+  nothing.
+- (16) `Get-NTFSOrphanedAccess`, `Get-NTFSOrphanedAudit`, and
+  `Get-NTFSSimpleAccess` ignore `-Account` and `-SecurityDescriptor`;
+  `Get-NTFSOrphanedAudit` writes collections; `SimpleFileSystemAccessRule`
+  has no format view.
+- (17) `removeSpecific` in `Remove-NTFSAccess/Audit` is never bound;
+  `Remove-NTFSAudit` leaves `appliesTo` uninitialized.
+
+#### C: Error handling
+
+- (18) `Copy-Item2`, `Move-Item2`, `Remove-Item2`: one failing path skips
+  the rest of `-Path` (`return` instead of `continue`).
+- (19) `Remove-NTFSAccess` continues after a failed read and writes a
+  second, misleading `RemoveAceError`.
+- (20) The inheritance cmdlets write `-PassThru` output in `finally`, even
+  after a failure.
+- (21) `New-NTFSHardLink` says the target path exists when it doesn't.
+
+#### D: Metadata and cosmetics
+
+- (22) Wrong or missing `[OutputType]` (`Test-Path2`, `Get-FileHash2`,
+  `Add-NTFSAudit`, `*-Item2`, inheritance cmdlets);
+  `Enable-/Disable-Privileges -PassThru` writes one collection;
+  `New-NTFSSymbolicLink -PassThru` returns `FileInfo` for folder links.
+- (23) Typos: "Privliege" in the `Get-NTFSEffectiveAccess` warning; "are
+  now enabled" in the `Disable-Privileges` verbose message.
+- (24) Dead code in `RemoveItem2.cs` and `OtherCmdlets.cs`.
+
+#### E: Maintainer decisions before changing behavior
+
+- `Clear-NTFSAccess -DisableInheritance` discards inherited entries: keep
+  that, or copy them?
+- `Set-NTFSInheritance` defaults are the opposite of the dedicated
+  inheritance cmdlets: align?
+- The audit inheritance switches are named `*AccessRules`: add
+  `*AuditRules` aliases?
+- `Get-FileHash2` fails in PowerShell 7 (`RIPEMD160`): drop the algorithm
+  there, load it lazily, or deprecate the cmdlet?

.memory-bank/systemPatterns.md

@@ -41,51 +41,21 @@ NTFSSecurity.dll ── cmdlets ──> Security2.dll (FileSystemAccessRule2,
 
 ## Decisions
 
-### Decision 1: Use the canonical Memory Bank base
+Each Decision record is a file in `decisions/`; read only the relevant ones.
 
-- Choice: Keep durable project context in .memory-bank.
-- Rationale: Preserve evidence-backed context across sessions.
+| # | Decision |
+| --- | --- |
+| 1 | [Use the canonical Memory Bank base](decisions/0001-canonical-memory-bank.md) |
+| 2 | [Cmdlet reference stays platyPS markdown](decisions/0002-platyps-cmdlet-reference.md) |
+| 3 | [Document the source at HEAD](decisions/0003-document-source-at-head.md) |
+| 4 | [Online help points to GitHub](decisions/0004-online-help-on-github.md) |
+| 5 | [Document defects, don't fix them in docs work](decisions/0005-document-defects-separately.md) |
+| 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) |
 
-### Decision 2: Cmdlet reference stays platyPS markdown
+## Patterns
 
-- Choice: `Docs/Cmdlets/*.md` keep the platyPS 0.14 schema 2.0.0 layout
-  (upper-case section headings, YAML parameter blocks, one paragraph per
-  line) so `Update-MarkdownHelp` and `New-ExternalHelp` round-trip.
-- Rationale: `appveyor.yml` checks the pages with `Update-MarkdownHelp`;
-  the same files can generate MAML help.
-
-### Decision 3: Document the source at HEAD
-
-- Choice: Docs describe the code on `master`. Where HEAD differs from the
-  latest Gallery release, the page says which version changed.
-- Rationale: The user asked to align docs with the actual code; the only
-  current difference is `Remove-Item2 -PassThru` (4.2.6 spells `-PassThur`).
-
-### Decision 4: Online help points to GitHub
-
-- 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`.
-
-### Decision 5: Document defects, don't fix them in docs work
-
-- Choice: Code defects found while documenting are described on the affected
-  page (workaround or limitation) and listed in `progress.md`; source code is
-  changed only in separate, tested work.
-- Rationale: No build toolchain was available to verify code changes, and
-  the docs must describe current behavior.
-
-### Decision 6: CI checks the docs against a build of the source
-
-- Choice: `appveyor.yml` builds `NTFSSecurity.csproj` and runs
-  `Update-MarkdownHelp` against `NTFSSecurity\bin\Release`, not against the
-  module from the PowerShell Gallery.
-- Rationale: Checking against the last release fails for every unreleased
-  parameter change (PR #91 failed on `Remove-Item2 -PassThru`) and never
-  compiled the code.
-
-### Pattern: verifying documentation
+### Verifying documentation
 
 - Run platyPS in Windows PowerShell 5.1 against a module build; a copy of
   `Docs/Cmdlets` must round-trip through `Update-MarkdownHelp` unchanged.

.memory-bank/techContext.md

@@ -50,6 +50,9 @@ source: repository evidence
   attached to the fork `Sup3rlativ3/NTFSSecurity`.
 - `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
+  get no entry
+  ([Decision 7](decisions/0007-changelog-user-visible-only.md)).
 
 ## Validation