NTFSSecurity/.memory-bank/techContext.md

---
status: current
last-verified: 2026-10-10
owner: active-agent
source: repository and executable evidence
---

# Tech context

## Stack

- Legacy C# projects, .NET Framework 4.5.2, `NTFSSecurity.sln`.
  Cmdlets depend on Security2, PrivilegeControl/ProcessPrivileges, and
  AlphaFS 2.2.x. System.Management.Automation reference: 10.0.10586.0.
- Module supports Windows PowerShell 5.1 and PowerShell 7; 36 cmdlets.
  Manifest initializes helper assemblies, aliases, type data, formatting,
  and committed help generated from `Docs/Cmdlets` (platyPS 0.14/schema 2).
- CI: `.github/workflows/ci.yml`, scripts in `.github/scripts`; GitHub
  renders Docs and publishes a generated wiki. No separate docs site.

## Current environment

- Host `ExHost`: Windows Server 2025 VM, native x64, elevated agent;
  repository `V:\Git\NTFSSecurity`. AutomatedLab 5.61.704, Hyper-V,
  approved lab `WindowsAccessControlLab` (Decision 20).
- Build Release only: Debug writes to Program Files. Native .NET Framework
  MSBuild plus Roslyn `Microsoft.Net.Compilers` 4.2.0 and .NET 4.5.2
  reference assemblies work; legacy compiler fails CS0136, dotnet MSBuild
  fails binary resources MSB3822/MSB3823. Build packages are already cached
  in `packages`; compiler/tools are under TEMP `ntfs-build`.
- Pester 5.7.1 is in
  `V:\Git\WindowsAccessControl\output\RequiredModules\Pester\5.7.1`.
  platyPS 0.14.2 and MarkdownLinkCheck 0.2.0 are under TEMP `ntfs-docs-tools`.
  PSScriptAnalyzer and PSResourceGet are available in PowerShell 7.
- Use Desktop's module paths in Desktop children, not inherited Core-only
  paths. Never import NTFSSecurity in the agent shell; every package/build
  runs in a new process. Current prereleases share assembly version 5.0.0.0.
- GitHub CLI: `C:\Program Files\GitHub CLI\gh.exe`, signed in as raandree.
  Read-only queries work; remote mutations belong to the maintainer.
- LabSources: `V:\LabSources`. The first lab's machines are Server 2025; the
  matrix lab `NtfsSecurityOsMatrixLab` adds Server 2019/2022 and Windows 11.

## Constraints

- Manifest: ModuleVersion 5.0.0, prerelease rc7, published 2026-10-10 (tag at
  `fa0701b`). Latest stable 4.2.6. The reuse test fails if `$publishedVersions`
  holds the manifest's version: add rc7 in the change that sets the next one.
- Changed-section writes preserve unchanged owner/group/DACL/SACL (19).
  Roots use root-folder APIs, not AlphaFS device security (#41).
- CHANGELOG contains user-visible changes only (7); tests and CI-only fixes
  get no entry. No stable release until Decision 21 gates close.
- Honor separate topic branches, no amendment, two AI co-author trailers.
  Never work around remote-mutation blocking. Provide each maintainer
  command separately at reply end, no question dialog after commands.
  Issue references use no closing keyword unless closure is intended.
- Lab passwords stay in memory and are lab-only; no secret in repository,
  logs, or process arguments. Live ACL mutations occur only in the lab.

## Build and focused checks

- Build `NTFSSecurity\NTFSSecurity.csproj` with Configuration=Release,
  Framework MSBuild, TargetFrameworkRootPath/FrameworkPathOverride to
  `packages\Microsoft.NETFramework.ReferenceAssemblies.net452.1.0.3\build`,
  CscToolPath to the cached compiler. Expected legacy CS1591/CS0618 warnings
  are not new failures. Never copy a mutated DLL into acceptance artifacts.
- Pester/builds run in detached monitored child processes through
  `Start-DetachedPowerShell.ps1`; use unique TEMP logs/result paths and an
  explicit-PID watcher. No foreground sleep/poll loop. Long payloads use
  a script file: nested Base64 encoding can exceed Windows command limits.
- Focused helper: TEMP `ntfs-focused\Start-FocusedRuns.ps1`; detach that
  driver too because its internal wait loop must not block the agent shell.
- TEMP `ntfs-docs-tools\Invoke-ChangeChecks.ps1 -File <relative paths>`
  performs AST/analyzer/lint/help checks. Absolute input paths misroute
  cmdlet pages. Check actual analyzer/lint output, not just helper exit.
- actionlint 1.7.12 checks the workflow. Script changes use AST parse and
  PSScriptAnalyzer; prose Markdown uses MD013 and changelog siblings-only
  repeated-heading allowance. Native error codes must be checked explicitly.
- Documentation: run platyPS in Desktop, generate external help, rebuild,
  require an unchanged Markdown round trip. Links in Docs are checked
  relatively; Wiki tests cover generated anchors, not arbitrary web URLs.

## CI and packaging

- CI `build` on windows-2025 installs tools, restores dependencies, builds
  Release, round-trips pages/help, checks links, and runs the suite in
  Desktop/Core, elevated/basic user. Lab tests are explicitly excluded.
- `.github/scripts/Invoke-TestsAsBasicUser.ps1` launches a SAFER Normal User
  token. Result paths may be absolute or repository-relative: Path.Combine
  then GetFullPath, not Join-Path with a rooted child.
- Packaging needs Compress-PSResource (Core 7.4+). New-ModulePackage copies
  only FileList, validates the manifest, creates nupkg plus NTFSSecurity.zip.
  Check package/file hashes and test the extracted artifact, not build extras.
- Release runs only for validated version tags in powershell-gallery; the API
  key is the environment secret PSGALLERY_API_KEY. The rules of
  `Publish-ModulePackage` are in `systemPatterns.md`. Read status through
  `gh pr checks` and `gh run view --log-failed`. A successful Gallery upload
  followed by HTTP 409 does not prove its retry chronology.

## Coverage and test eligibility

- AltCover 9.0.145 net472 instruments a copied Release build with PDBs,
  OpenCover format, localSource, excluding AlphaFS/System.Management.Automation.
  Do not use --save: collection previously retained only one process's hits.
- Freeze a git worktree, instrument its NTFSSecurity\bin\Release, run all
  four configurations sequentially with the real CI wrappers, then
  AltCover runner --collect recalculates the report. Compute option paths
  before passing native arguments, not inline Join-Path expressions.
- Report sequence points, not unique source lines. Four-run baselines:
  `3442194` 2,641/3,559 (74.21%); `5a5d58b` 3,192/3,634 (87.84%); `fa0701b`
  (rc7) 3,198/3,649 (87.64%); `61e936e` 3,258/3,664 (88.92%). The code
  changes the denominators: never present these as same-source increments.
  The branch summary of the tool adds a point to most methods (never visited
  for the 626 without a branch): report the explicit branch points
  (1,090/1,168, 93.32%), not the summary percentage. Suite at `61e936e`: 1,459
  per configuration, zero failures (skipped: 26 and 57 elevated, 276 and 307
  basic, Desktop and Core).
- NUnit skipped ForEach names retain placeholders and parameter tuples,
  executed names expand them: raw-name intersection and positional alignment
  are invalid. Check skip eligibility by row: run the suite once per
  configuration with Pester PassThru and match skipped with executed rows by
  file, line, path, name, and data (discovery alone misses tests that skip
  while running; write primitives, as `ConvertTo-Json` of rich rows hangs).
- Live and domain-member coverage: instrument a copy of the package without
  `--portable`, with an absolute report path outside the payload
  (`C:\NtfsMatrixProbe\Coverage`, `icacls` Authenticated Users modify) and a
  SYSTEM task that snapshots the report after each process (a role that is not
  an administrator of the client can't write next to the module). It counts
  only when its counts equal the uninstrumented acceptance and every role
  logged a flush. Merge by position, never by `uspid`. PowerShell reads the
  getter of a parameter that it binds from a piped object: unvisited getters
  point at missing pipeline tests.
- Remaining inventory at `61e936e`: 406 points in 187 methods, classified by
  rule (`Tests/Coverage`). Preserve raw XML, row CSVs, logs, commit identity,
  and build hashes: the frozen Build rewrites its hash file, so save the
  hashes of the measured assemblies (AltCover `__Saved` copies) first.
- Mutation proofs: bounded one-statement changes on a second frozen worktree,
  source restored exactly and rebuilt (an escape can be an overlap, an
  equivalent mutant, or a masked case: check before changing a test). Red/green
  matrix for a fix: build each state in its own Release worktree, lay the
  final `Tests` over it, count failed rows per name in all four
  configurations, and keep logs and hashes (Handoff 1's first red runs were
  deleted and could not be reproduced).

## Lab acceptance

- Defaults: F1ADC1 (domain), F1AFile2 (server), F1AFile1 (client), all in
  a.forest1.net. Foreign accounts use F1BDC1, F2DC1, F3DC1 and existing trusts.
  Controller accepts alternate machines; changing topology/OS scope waits
  for a maintainer decision. Do not repurpose another project's shared VMs.
- Before a run: authenticated WinRM, LDAP RootDSE, Kerberos tickets, member
  secure channels, clocks; checkpoint only approved targets. New checkpoints
  report Standard even after a successful ProductionOnly request (policy
  restored, no rollback): Production is unverified, not a passed safety check.
- Run Tests\Lab\Invoke-NTFSSecurityLabTest.ps1 in elevated Desktop with
  -Version for hash-checked Gallery packages or -ModulePath for the extracted
  build artifact, both editions. Per version/edition: Delegate, ServerAdmin,
  Admin on client, then Server independently checks persisted state.
- Controller writes Summary.json even when tests fail: validate every role,
  exit code, failure name, and total; DONE alone is not acceptance evidence.
  Desktop ConvertFrom-Json can wrap arrays: enumerate the result and compare
  full Describe-prefixed names. Never gate cleanup on the global Error.Count
  (it includes handled errors); verify the footprint independently.
- Remote Authz answers administrators and Access Control Assistance
  Operators (S-1-5-32-579); other accounts get access denied (check the
  firewall when its RPC fails). Expected rights use S4U tokens. A domain
  member offers the remote interface to every caller, so the default
  `-ServerName localhost` was denied for a non-administrator; hosts outside a
  domain don't, so the host and CI missed it. Since `fdd7a8b` the local
  manager answers for a name of this computer; another computer stays denied.
- A live test is evidence of a fix only when it fails on the build without
  the fix: run the same tests, controller, and lab against the candidate and
  the base, a new process per edition, and join the results by edition, role,
  and full test name; tests that pass on both are controls (record of
  2026-10-09). PowerShell variables ignore case: `$edition` overwrote
  `$Edition`.
- RemoveFixture after the run; verify OUs/accounts, share, folders, local
  memberships, and test profiles removed. Credentials must never be printed.

### Operating-system matrix (Decision 24)

- Lab `NtfsSecurityOsMatrixLab`: OSDC1 (Server 2025), OSFile19/22/25 (Server
  2019/2022/2025), OSWin11E (Windows 11 Enterprise Evaluation 22H2, the domain
  client), OSWin11 (Windows 11 Pro 26H1, suite only). Kit
  `Tests\Lab\Acceptance`; record
  `Tests\Lab\Acceptance-2026-10-10-os-matrix.md` (procedure, limits);
  the lessons of building it are in `deployment-notes.md`.
- Run the module's own suite on every machine first (`Run-MatrixLocalSuite.ps1`
  as scheduled tasks with a batch logon at the highest run level; a remoting
  child has every privilege enabled). One `Import-Lab` at a time. Compare skips
  as multisets against the host. Hash each candidate and its package: builds
  aren't byte-reproducible.
- The 26H1 client can't keep its secure channel to a Server 2025 DC (suite
  only); the 22H2 evaluation client shuts down every hour: keep a run under an
  hour and test a domain session, not `nltest /sc_verify`.
- A fixture that re-creates an account name gets stale answers for about ten
  minutes, for the baseline and the candidate alike (mechanism unknown; no
  remedy but waiting). The controller names the case-3 account anew for each
  fixture; the replay and the model are in the record. `Test-MatrixCleanup.ps1`
  verifies and repairs the probe's profiles and group entries.