(MODULES-11830) Expand Windows specifics in moduleroot/CLAUDE.md

Replace the 4-bullet Windows stub in the OS-conditional CLAUDE.md template with
a full "Windows specifics" section, consolidating the MODULES-11830 artifact
into this PR (which now delivers both MODULES-11829 and MODULES-11830).

Adds Windows guidance covering: platform basics (Chocolatey/MSI providers, SCM
services, backslash/case-insensitive paths, ACL permissions), DSC resource
patterns (machine-generated dsc_* types, mangled names, Sensitive() credentials,
Test-TargetResource idempotency), PowerShell exec idioms (powershell provider,
idempotent onlyif/unless, ruby-pwsh, -EncodedCommand), scheduled_task semantics
(taskscheduler_api2, trigger comparison, compatibility), native-extension Ruby
gotchas (win32-* gems guarded by microsoft_windows?, Linux CI stubbing), and
Windows Litmus/acceptance (real VMs not Docker, WinRM, reboots).

Stays inside the existing `<% if has_windows -%>` conditional so it renders only
for Windows-supporting modules. Pure ASCII (PDK's diff engine chokes on non-ASCII
under a non-UTF-8 locale).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: imaqsood

moduleroot/CLAUDE.md.erb

@@ -236,11 +236,82 @@ Applies to modules whose primary interface is Bolt tasks (`tasks/`):
 <% if has_windows -%>
 ## Windows specifics
 
-- **Package management**: Chocolatey / MSI / Windows installer providers; not apt/yum.
-- **Services**: managed via the Windows SCM (`sc.exe` / the service provider), no systemd.
-- **Tasks**: PowerShell tasks are `<name>.ps1`; mind execution policy and quoting.
-- **Paths**: Puppet installs under `C:\Program Files\Puppet Labs\Puppet`; use backslash paths and
-  `windows`-appropriate file resources. Line endings and case-insensitive paths matter in specs.
+Windows modules have a meaningfully different surface from Linux. Read these before touching
+iis/sqlserver/registry/scheduled_task/dsc-style modules.
+
+### Platform basics
+
+- **Package management**: Chocolatey, MSI, and the Windows installer providers -- not apt/yum. Gate
+  provider-specific behaviour on `$facts['os']['family'] == 'windows'`.
+- **Services**: managed via the Windows SCM (`sc.exe` / the `service` provider), no systemd. Service
+  names are case-insensitive; account for `LocalSystem`/`NetworkService`/named-account `logon` config.
+- **Paths**: Puppet installs under `C:\Program Files\Puppet Labs\Puppet` (ruby at
+  `...\puppet\bin\ruby.exe`). Use backslash paths in resources and double them in Ruby string
+  literals. Paths are case-insensitive and `\`-separated; normalise before comparing in providers so
+  specs stay idempotent. CRLF line endings and BOM handling matter in file specs.
+- **Permissions**: there is no POSIX `mode`; model ACLs with the `puppetlabs/acl` module, not
+  `file { mode => '0644' }`.
+
+### DSC resource patterns
+
+Applies to the generated `puppetlabs/dsc`-family modules (built from PowerShell DSC Resources):
+
+- Types and providers under `lib/puppet/type/dsc_*.rb` and `lib/puppet/provider/dsc_*` are
+  **machine-generated by the DSC builder -- never hand-edit them**; regenerate from the upstream PS
+  module instead.
+- Resource and property names are mangled: PowerShell `MyResource`/`PropertyName` become
+  `dsc_myresource` with `dsc_propertyname` parameters (lowercased, `dsc_`-prefixed).
+- Embedded CIM instances (e.g. `MSFT_Credential`) are passed as hashes; credentials use
+  `{ 'user' => ..., 'password' => Sensitive('...') }` and **must** be wrapped in `Sensitive()` so the
+  value never lands in logs or the catalog in clear text.
+- Idempotency is delegated to the resource's `Test-TargetResource`; the provider invokes it through
+  the persistent PowerShell host (ruby-pwsh). Don't add a parallel `exec` to "fix" drift a DSC
+  resource already manages.
+
+### PowerShell exec idioms
+
+- Prefer a real type/provider or a DSC resource over shelling out. When you must run PowerShell, use
+  the `puppetlabs/powershell` `exec` provider: `exec { 'x': provider => 'powershell', ... }`.
+- Always make `exec` conditional and idempotent with `onlyif`/`unless` PowerShell that sets a non-zero
+  exit code on the "needs change" path -- never an unconditional `command`.
+- Providers reuse a long-lived PowerShell process via `ruby-pwsh` (`Pwsh::Manager`) for performance;
+  prefer it over spawning `powershell.exe` per call.
+- Quoting cmd/PowerShell nesting is error-prone: prefer here-strings or `-EncodedCommand` (base64) for
+  non-trivial scripts, and pass `-NonInteractive -ExecutionPolicy Bypass` so runs don't hang or get
+  blocked by machine policy.
+
+### scheduled_task semantics
+
+Applies to the `puppetlabs/scheduled_task` type:
+
+- Default to the modern `taskscheduler_api2` provider; the legacy `win32_taskscheduler` provider
+  exists for back-compat only -- don't reintroduce it for new work.
+- `trigger` is an array of hashes (`schedule`, `start_time`, `every`, `day_of_week`, ...). Most
+  idempotency bugs come from trigger comparison: times are interpreted in the target's local timezone
+  and round-tripped, so assert a second `apply` is a no-op in acceptance.
+- Set `compatibility` deliberately when a trigger type needs a newer Task Scheduler schema; a mismatch
+  silently drops or rewrites triggers.
+
+### Native-extension Ruby gotchas
+
+- Windows providers often depend on native gems (`win32-service`, `win32-dir`, `win32-security`,
+  `ffi`) that only load on Windows. Guard `require`s and Windows-only code paths with
+  `Puppet.features.microsoft_windows?` so the file still loads on the Linux CI runner.
+- **Unit specs run on Linux** in CI even for Windows modules. Stub the Win32/FFI calls and
+  `microsoft_windows?` rather than invoking the real API, and assert the *commands generated* and
+  *state parsed* -- the same rule as any provider spec.
+- WinRM/UTF-16, CRLF, and backslash-path handling are common spec foot-guns; normalise in the code,
+  not the test.
+
+### Litmus / acceptance on Windows
+
+- Windows targets are **not** Docker containers. Litmus provisions real VMs (vmpooler / ABS / cloud),
+  so the Linux `litmus:provision_list[default]` Docker flow does not apply. Provision explicitly, e.g.
+  `bundle exec rake 'litmus:provision[vmpooler, windows-2022-x86_64]'`.
+- The agent connects over **WinRM**, which is slower than SSH and occasionally flaky -- keep acceptance
+  manifests tight and idempotent.
+- Reboots are real and sometimes required (installers, feature changes); orchestrate them with the
+  `puppetlabs/reboot` module rather than ad-hoc `exec` restarts.
 
 <% end -%>
 ## Review policy (outcome-based)