fix(securitydescriptor): make -SecurityDescriptor of Set-NTFSSecurityDescriptor the first positional parameter

Set-NTFSSecurityDescriptor declared -SecurityDescriptor at Position = 2,
its only positional parameter; every sibling that takes a security
descriptor or a path takes its first positional parameter at 1. Moved
to Position = 1 for consistency. A positional call with one argument
already bound to it, because it was the only positional parameter in
its only parameter set, so no script that calls the cmdlet positionally
can notice a difference; this is cosmetic, as Decision 27 describes it.

Tests\SecurityDescriptor.Tests.ps1 adds a characterization-turned-pin
test: the declared Position is 1, and Set-NTFSSecurityDescriptor $sd
still works positionally. RED before the change (Position was 2), GREEN
after, in all four configurations.

Docs\Cmdlets\Set-NTFSSecurityDescriptor.md: Position: 1 in the yaml
block of -SecurityDescriptor.

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

Docs/Cmdlets/Set-NTFSSecurityDescriptor.md

@@ -95,7 +95,7 @@ Parameter Sets: (All)
 Aliases:
 
 Required: True
-Position: 2
+Position: 1
 Default value: None
 Accept pipeline input: True (ByPropertyName, ByValue)
 Accept wildcard characters: False

NTFSSecurity/SecurityDescriptorCmdlets/SetSecurityDescriptor.cs

@@ -11,7 +11,7 @@ namespace NTFSSecurity
     {
         private SwitchParameter passThru;
 
-        [Parameter(Mandatory = true, Position = 2, ValueFromPipeline = true, ValueFromPipelineByPropertyName = true)]
+        [Parameter(Mandatory = true, Position = 1, ValueFromPipeline = true, ValueFromPipelineByPropertyName = true)]
         public FileSystemSecurity2[] SecurityDescriptor
         {
             get { return securityDescriptors.ToArray(); }

Tests/SecurityDescriptor.Tests.ps1

@@ -73,6 +73,24 @@ Describe 'Get-NTFSSecurityDescriptor' {
 }
 
 Describe 'Set-NTFSSecurityDescriptor' {
+    Context 'Parameter declaration' {
+        # Its siblings (Get-NTFSSecurityDescriptor and the cmdlets with a -SecurityDescriptor parameter set) take
+        # their first positional parameter at 1; -SecurityDescriptor was the only one at 2 (6c), cosmetic only: a
+        # positional call with one argument already bound to it, because it was the only positional parameter.
+        It 'Should declare -SecurityDescriptor at position 1, and still accept it positionally' {
+            (Get-Command -Name 'Set-NTFSSecurityDescriptor').Parameters['SecurityDescriptor'].Attributes.Position | Should -Be 1
+
+            $file = New-TestSandboxItem -Sandbox $sandbox -Name 'PositionalWrite'
+            Assert-TestSandboxPath -Sandbox $sandbox -Path $file
+            $sd = Get-NTFSSecurityDescriptor -Path $file
+            Add-NTFSAccess -SecurityDescriptor $sd -Account 'Everyone' -AccessRights ReadData
+
+            Set-NTFSSecurityDescriptor $sd
+
+            @(Get-EveryoneRule -Path $file) | Should -HaveCount 1
+        }
+    }
+
     Context 'When a cmdlet added an access entry to the descriptor' {
         It 'Should write the entry as the only explicit entry of the item' {
             $file = New-TestSandboxItem -Sandbox $sandbox -Name 'AddedEntry'