aid-installer 1.1.1 → 2.0.1

package/lib/AidInstallCore.psm1

@@ -47,6 +47,10 @@
 
 Set-StrictMode -Version Latest
 
+# Enable TLS 1.2 for HTTPS. Windows PowerShell 5.1 (.NET Framework) can default to
+# SSL3/TLS1.0, which GitHub/npm/pypi reject -> downloads fail. Harmless on PS7/.NET Core.
+try { [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12 } catch {}
+
 # Guard against being imported more than once.
 # Use Get-Variable with -ErrorAction SilentlyContinue to avoid strict-mode failure on first load.
 $_aidLoadedVar = Get-Variable -Name '_AID_INSTALL_CORE_LOADED' -Scope Global -ErrorAction SilentlyContinue
@@ -58,10 +62,18 @@ $script:_CopyCountCopied   = 0
 $script:_CopyCountUpToDate = 0
 $script:_CopyCountUpdated  = 0
 $script:_CopyCountSkipped  = 0
+$script:_CopyCountFailed   = 0
 
 # Module-level prune counter. Reset by Invoke-PruneToolDirs before each prune pass.
 $script:_PruneRemoved = 0
 
+# Module-level project-provisioning state (work-007). Reset by Install-AidTool.
+$script:_SeededSettings  = $false
+$script:_GitignoreAction = 'unchanged'
+# Settings format stamp. MUST equal bin/aid AID_SUPPORTED_FORMAT / bin/aid.ps1
+# AidSupportedFormat. Used to stamp a seeded settings.yml so the format gate is quiet.
+$script:_AidSupportedFormat = 1
+
 # ---------------------------------------------------------------------------
 # Constants
 # ---------------------------------------------------------------------------
@@ -81,6 +93,21 @@ function script:Get-RootAgentFile {
     }
 }
 
+# Get-RootDir <tool> - return the tool's install-tree root dir name (relative to
+# the project root). The AID-own subtree lives at <root>/aid/ (e.g. .claude/aid/).
+# Mirrors the per-tool dispatch in Install-AidTool and the bash _root_dir helper.
+function script:Get-RootDir {
+    param([string]$Tool)
+    switch ($Tool) {
+        'claude-code' { return '.claude' }
+        'codex'       { return '.codex' }
+        'cursor'      { return '.cursor' }
+        'copilot-cli' { return '.github' }
+        'antigravity' { return '.agent' }
+        default       { return '' }
+    }
+}
+
 # ---------------------------------------------------------------------------
 # Utility
 # ---------------------------------------------------------------------------
@@ -357,7 +384,13 @@ function Copy-AidFile {
     }
 
     if (-not (Test-Path $Dst -PathType Leaf)) {
-        Copy-Item -LiteralPath $Src -Destination $Dst -Force
+        try {
+            Copy-Item -LiteralPath $Src -Destination $Dst -Force -ErrorAction Stop
+        } catch {
+            [Console]::Error.WriteLine("ERROR: AidInstallCore: copy failed: $Dst -- $_")
+            $script:_CopyCountFailed++
+            return
+        }
         $script:_CopyCountCopied++
         if ($AidVerbose) { Write-Host "Copied: $Dst" }
         return
@@ -373,15 +406,22 @@ function Copy-AidFile {
         return
     }
 
-    # File exists and differs.
-    if ($Force) {
-        Copy-Item -LiteralPath $Src -Destination $Dst -Force
-        $script:_CopyCountUpdated++
-        if ($AidVerbose) { Write-Host "Updated: $Dst" }
-    } else {
-        $script:_CopyCountSkipped++
-        if ($AidVerbose) { Write-Host "Skipped (differs; use --force): $Dst" }
+    # File exists and differs -> always overwrite (work-007).
+    # AID-owned files track the bundle, which is the source of truth, so an
+    # add/update must bring them current. $Force is retained in the signature for
+    # back-compat and bash<->PS parity but no longer gates this overwrite:
+    # skip-on-diff silently left stale files behind on in-place upgrades. User-owned
+    # root agent files (CLAUDE.md/AGENTS.md) never reach Copy-AidFile -- they are
+    # handled by Copy-RootAgentFile, which keeps its own force gating.
+    try {
+        Copy-Item -LiteralPath $Src -Destination $Dst -Force -ErrorAction Stop
+    } catch {
+        [Console]::Error.WriteLine("ERROR: AidInstallCore: copy failed: $Dst -- $_")
+        $script:_CopyCountFailed++
+        return
     }
+    $script:_CopyCountUpdated++
+    if ($AidVerbose) { Write-Host "Updated: $Dst" }
 }
 
 # Copy-AidDir <srcDir> <dstDir> [force] [aidVerbose]
@@ -434,8 +474,13 @@ function script:Test-AidHeadingStem {
     $stem = $Line.Substring(3)  # strip "## "
     # Strip trailing parenthetical: " (anything)"
     $stem = $stem -replace ' \([^)]*\)$', ''
+    # Stems must cover EVERY "## " heading in the shipped AID:BEGIN/END region
+    # (Tracking discipline, Knowledge Base, Workflow, Review output format,
+    # Permissions). A missing stem duplicates that section on C2 migration
+    # (work-007: Workflow was omitted). Parity with bash is_aid_heading.
     switch ($stem) {
         'Knowledge Base'       { return $true }
+        'Workflow'             { return $true }
         'Review output format' { return $true }
         'Permissions'          { return $true }
         'Tracking discipline'  { return $true }
@@ -678,7 +723,7 @@ function Read-ManifestToolPaths {
     try {
         $data = Get-Content -LiteralPath $ManifestPath -Raw | ConvertFrom-Json
         $toolData = if ($data.tools -and ($data.tools.PSObject.Properties.Name -contains $Tool)) { $data.tools.$Tool } else { $null }
-        if ($toolData -and $toolData.paths) {
+        if ($toolData -and $toolData.PSObject.Properties['paths'] -and $toolData.paths) {
             return @($toolData.paths)
         }
     } catch {}
@@ -693,7 +738,7 @@ function Read-ManifestToolVersion {
     try {
         $data = Get-Content -LiteralPath $ManifestPath -Raw | ConvertFrom-Json
         $toolData = if ($data.tools -and ($data.tools.PSObject.Properties.Name -contains $Tool)) { $data.tools.$Tool } else { $null }
-        if ($toolData -and $toolData.version) { return $toolData.version }
+        if ($toolData -and $toolData.PSObject.Properties['version'] -and $toolData.version) { return [string]$toolData.version }
     } catch {}
     return ''
 }
@@ -706,9 +751,15 @@ function Read-ManifestRootAgent {
     try {
         $data = Get-Content -LiteralPath $ManifestPath -Raw | ConvertFrom-Json
         $toolData = if ($data.tools -and ($data.tools.PSObject.Properties.Name -contains $Tool)) { $data.tools.$Tool } else { $null }
-        if ($toolData -and $toolData.root_agent_files) {
-            foreach ($entry in $toolData.root_agent_files) {
-                if ($entry.path -eq $FileName) { return $entry.sha256 }
+        # Guard root_agent_files: absent on old-format manifests; PSObject.Properties['key'] is
+        # safe under Set-StrictMode -Version Latest unlike direct property access.
+        $raf = if ($toolData -and $toolData.PSObject.Properties['root_agent_files']) { $toolData.root_agent_files } else { $null }
+        if ($raf) {
+            foreach ($entry in $raf) {
+                if ($entry.PSObject.Properties['path'] -and $entry.path -eq $FileName) {
+                    $sha = if ($entry.PSObject.Properties['sha256']) { $entry.sha256 } else { '' }
+                    return $sha
+                }
             }
         }
     } catch {}
@@ -723,9 +774,10 @@ function Read-ManifestRootAgentStatus {
     try {
         $data = Get-Content -LiteralPath $ManifestPath -Raw | ConvertFrom-Json
         $toolData = if ($data.tools -and ($data.tools.PSObject.Properties.Name -contains $Tool)) { $data.tools.$Tool } else { $null }
-        if ($toolData -and $toolData.root_agent_files) {
-            foreach ($entry in $toolData.root_agent_files) {
-                if ($entry.path -eq $FileName) {
+        $raf = if ($toolData -and $toolData.PSObject.Properties['root_agent_files']) { $toolData.root_agent_files } else { $null }
+        if ($raf) {
+            foreach ($entry in $raf) {
+                if ($entry.PSObject.Properties['path'] -and $entry.path -eq $FileName) {
                     if ($entry.PSObject.Properties['status']) { return $entry.status }
                     return 'owned'
                 }
@@ -880,8 +932,11 @@ function Write-AidManifest {
     }
 
     # Top-level installed_at: preserve existing.
+    # Guard via PSObject.Properties['key'] -- Set-StrictMode -Version Latest (active in this module)
+    # throws PropertyNotFoundException on direct access of absent properties.  Old-format manifests
+    # (schema:1) have no root-level installed_at; new-format ones (manifest_version:1) do.
     $topInstalledAt = $now
-    if ($existingData -and $existingData.installed_at) {
+    if ($existingData -and $existingData.PSObject.Properties['installed_at'] -and $existingData.installed_at) {
         $topInstalledAt = $existingData.installed_at
     }
 
@@ -895,17 +950,22 @@ function Write-AidManifest {
             $tid = $_.Name
             if ($tid -ne $Tool) {
                 $t   = $_.Value
-                $tP  = if ($t.paths) { [System.Collections.Generic.List[string]]($t.paths) } else { [System.Collections.Generic.List[string]]::new() }
+                # Guard per-tool properties: old manifests lack root_agent_files; use
+                # PSObject.Properties['key'] check before direct access (StrictMode-safe).
+                $tP  = if ($t.PSObject.Properties['paths'] -and $t.paths) { [System.Collections.Generic.List[string]]($t.paths) } else { [System.Collections.Generic.List[string]]::new() }
                 $tR  = [System.Collections.Generic.List[hashtable]]::new()
-                if ($t.root_agent_files) {
-                    foreach ($e in $t.root_agent_files) {
+                $tRaf = if ($t.PSObject.Properties['root_agent_files']) { $t.root_agent_files } else { $null }
+                if ($tRaf) {
+                    foreach ($e in $tRaf) {
+                        $ePath   = if ($e.PSObject.Properties['path'])   { $e.path }   else { '' }
+                        $eSha256 = if ($e.PSObject.Properties['sha256']) { $e.sha256 } else { '' }
                         $st = if ($e.PSObject.Properties['status']) { $e.status } else { 'owned' }
-                        $tR.Add(@{ path = $e.path; sha256 = $e.sha256; status = $st })
+                        if ($ePath) { $tR.Add(@{ path = $ePath; sha256 = $eSha256; status = $st }) }
                     }
                 }
                 $toolsMap[$tid] = @{
-                    Version       = if ($t.version) { $t.version } else { '' }
-                    InstalledAt   = if ($t.installed_at) { $t.installed_at } else { $now }
+                    Version       = if ($t.PSObject.Properties['version'] -and $t.version) { [string]$t.version } else { '' }
+                    InstalledAt   = if ($t.PSObject.Properties['installed_at'] -and $t.installed_at) { $t.installed_at } else { $now }
                     Paths         = $tP
                     RootAgentFiles = $tR
                 }
@@ -921,14 +981,14 @@ function Write-AidManifest {
 
     # tool installed_at: preserve existing.
     $toolInstalledAt = $now
-    if ($existingTool -and $existingTool.installed_at) {
+    if ($existingTool -and $existingTool.PSObject.Properties['installed_at'] -and $existingTool.installed_at) {
         $toolInstalledAt = $existingTool.installed_at
     }
 
     # De-duplicate paths (union, preserving order: existing first, then new).
     $seenPaths   = [System.Collections.Generic.HashSet[string]]::new()
     $mergedPaths = [System.Collections.Generic.List[string]]::new()
-    if ($existingTool -and $existingTool.paths) {
+    if ($existingTool -and $existingTool.PSObject.Properties['paths'] -and $existingTool.paths) {
         foreach ($p in $existingTool.paths) {
             if ($seenPaths.Add($p)) { $mergedPaths.Add($p) }
         }
@@ -939,10 +999,13 @@ function Write-AidManifest {
 
     # Merge root_agent_files: update or add per path.
     $rafMap = [System.Collections.Specialized.OrderedDictionary]::new()
-    if ($existingTool -and $existingTool.root_agent_files) {
-        foreach ($e in $existingTool.root_agent_files) {
+    $existingRaf = if ($existingTool -and $existingTool.PSObject.Properties['root_agent_files']) { $existingTool.root_agent_files } else { $null }
+    if ($existingRaf) {
+        foreach ($e in $existingRaf) {
+            $ePath   = if ($e.PSObject.Properties['path'])   { $e.path }   else { '' }
+            $eSha256 = if ($e.PSObject.Properties['sha256']) { $e.sha256 } else { '' }
             $st = if ($e.PSObject.Properties['status']) { $e.status } else { 'owned' }
-            $rafMap[$e.path] = @{ path = $e.path; sha256 = $e.sha256; status = $st }
+            if ($ePath) { $rafMap[$ePath] = @{ path = $ePath; sha256 = $eSha256; status = $st } }
         }
     }
     foreach ($entry in $RootEntries) {
@@ -995,23 +1058,27 @@ function Remove-ManifestTool {
     }
 
     # Build tools map without the target tool.
+    # Guard all per-tool property accesses via PSObject.Properties['key'] (StrictMode-safe).
     $toolsMap = [System.Collections.Specialized.OrderedDictionary]::new()
     if ($data.tools) {
         $data.tools.PSObject.Properties | ForEach-Object {
             $tid = $_.Name
             if ($tid -ne $Tool) {
                 $t  = $_.Value
-                $tP = if ($t.paths) { [System.Collections.Generic.List[string]]($t.paths) } else { [System.Collections.Generic.List[string]]::new() }
+                $tP = if ($t.PSObject.Properties['paths'] -and $t.paths) { [System.Collections.Generic.List[string]]($t.paths) } else { [System.Collections.Generic.List[string]]::new() }
                 $tR = [System.Collections.Generic.List[hashtable]]::new()
-                if ($t.root_agent_files) {
-                    foreach ($e in $t.root_agent_files) {
+                $tRaf = if ($t.PSObject.Properties['root_agent_files']) { $t.root_agent_files } else { $null }
+                if ($tRaf) {
+                    foreach ($e in $tRaf) {
+                        $ePath   = if ($e.PSObject.Properties['path'])   { $e.path }   else { '' }
+                        $eSha256 = if ($e.PSObject.Properties['sha256']) { $e.sha256 } else { '' }
                         $st = if ($e.PSObject.Properties['status']) { $e.status } else { 'owned' }
-                        $tR.Add(@{ path = $e.path; sha256 = $e.sha256; status = $st })
+                        if ($ePath) { $tR.Add(@{ path = $ePath; sha256 = $eSha256; status = $st }) }
                     }
                 }
                 $toolsMap[$tid] = @{
-                    Version        = if ($t.version) { $t.version } else { '' }
-                    InstalledAt    = if ($t.installed_at) { $t.installed_at } else { '' }
+                    Version        = if ($t.PSObject.Properties['version'] -and $t.version) { [string]$t.version } else { '' }
+                    InstalledAt    = if ($t.PSObject.Properties['installed_at'] -and $t.installed_at) { $t.installed_at } else { '' }
                     Paths          = $tP
                     RootAgentFiles = $tR
                 }
@@ -1024,8 +1091,8 @@ function Remove-ManifestTool {
         return
     }
 
-    $topIat = if ($data.installed_at) { $data.installed_at } else { ([System.DateTime]::UtcNow.ToString('yyyy-MM-ddTHH:mm:ssZ')) }
-    $topVer = if ($data.aid_version) { $data.aid_version } else { '0.0.0' }
+    $topIat = if ($data.PSObject.Properties['installed_at'] -and $data.installed_at) { $data.installed_at } else { ([System.DateTime]::UtcNow.ToString('yyyy-MM-ddTHH:mm:ssZ')) }
+    $topVer = if ($data.PSObject.Properties['aid_version'] -and $data.aid_version) { $data.aid_version } else { '0.0.0' }
 
     $json = script:Build-ManifestJson -TopInstalledAt $topIat -TopVersion $topVer -ToolsMap $toolsMap
 
@@ -1099,7 +1166,7 @@ function Invoke-AidProvisionSharedStateHome {
             "schema: 1",
             "projects:"
         )
-        Set-Content -LiteralPath $tmp -Value $seedLines -Encoding utf8NoBOM -ErrorAction Stop
+        [System.IO.File]::WriteAllText($tmp, (($seedLines) -join "`n") + "`n", [System.Text.UTF8Encoding]::new($false))
         Move-Item -LiteralPath $tmp -Destination $reg -Force -ErrorAction Stop
     } catch {
         Remove-Item -LiteralPath $tmp -Force -ErrorAction SilentlyContinue
@@ -1211,15 +1278,20 @@ function Invoke-PruneToolDirs {
         # Rule (d): prune now-empty subdirs (deepest first, skip the root itself).
         $subdirs = @(Get-ChildItem -LiteralPath $ADir -Recurse -Directory -ErrorAction SilentlyContinue)
         # Sort deepest first (longest path first by ordinal).
-        $subdirPaths = [string[]]($subdirs | ForEach-Object { $_.FullName })
-        [System.Array]::Sort($subdirPaths, [System.StringComparer]::Ordinal)
-        [System.Array]::Reverse($subdirPaths)
-        foreach ($dp in $subdirPaths) {
-            if (Test-Path $dp -PathType Container) {
-                $rem = @(Get-ChildItem -LiteralPath $dp -ErrorAction SilentlyContinue) | Select-Object -First 1
-                if (-not $rem) {
-                    Remove-Item -LiteralPath $dp -Force
-                    if ($AidVerbose) { Write-Host "Pruned dir: $dp" }
+        # Guard: pipeline over an empty @() returns $null on PowerShell; [System.Array]::Sort($null)
+        # throws "Value cannot be null" (reproduces on pwsh when the dir has no subdirectories,
+        # e.g. cursor/antigravity idempotent re-run after retired roots are already gone).
+        if ($subdirs.Count -gt 0) {
+            $subdirPaths = [string[]]($subdirs | ForEach-Object { $_.FullName })
+            [System.Array]::Sort($subdirPaths, [System.StringComparer]::Ordinal)
+            [System.Array]::Reverse($subdirPaths)
+            foreach ($dp in $subdirPaths) {
+                if (Test-Path $dp -PathType Container) {
+                    $rem = @(Get-ChildItem -LiteralPath $dp -ErrorAction SilentlyContinue) | Select-Object -First 1
+                    if (-not $rem) {
+                        Remove-Item -LiteralPath $dp -Force
+                        if ($AidVerbose) { Write-Host "Pruned dir: $dp" }
+                    }
                 }
             }
         }
@@ -1231,6 +1303,8 @@ function Invoke-PruneToolDirs {
     #       that map points copilot-cli at the .github ROOT (forbidden by R1).
     #       Scope is the R1-compliant set: .github/{agents,skills,aid} only.
     # -----------------------------------------------------------------------
+    # Per-tool scoping: new layout (work-005/delivery-001).
+    # Codex unified under .codex/; cursor and antigravity no longer ship rules/.
     switch ($Tool) {
         'claude-code' {
             & $pruneNativeDir (Join-Path $Target '.claude\agents')
@@ -1238,15 +1312,15 @@ function Invoke-PruneToolDirs {
             & $pruneAidSubtree (Join-Path $Target '.claude\aid')
         }
         'codex' {
-            # .codex ships only agents/; .agents ships skills/ + aid/ subtree.
+            # New unified layout: everything under .codex/ (agents, skills, aid).
             & $pruneNativeDir (Join-Path $Target '.codex\agents')
-            & $pruneNativeDir (Join-Path $Target '.agents\skills')
-            & $pruneAidSubtree (Join-Path $Target '.agents\aid')
+            & $pruneNativeDir (Join-Path $Target '.codex\skills')
+            & $pruneAidSubtree (Join-Path $Target '.codex\aid')
         }
         'cursor' {
+            # rules/ dir removed from new layout; agents/skills/aid remain.
             & $pruneNativeDir (Join-Path $Target '.cursor\agents')
             & $pruneNativeDir (Join-Path $Target '.cursor\skills')
-            & $pruneNativeDir (Join-Path $Target '.cursor\rules')
             & $pruneAidSubtree (Join-Path $Target '.cursor\aid')
         }
         'copilot-cli' {
@@ -1256,7 +1330,8 @@ function Invoke-PruneToolDirs {
             & $pruneAidSubtree (Join-Path $Target '.github\aid')
         }
         'antigravity' {
-            & $pruneNativeDir (Join-Path $Target '.agent\rules')
+            # rules/ dir removed from new layout; agents/skills/aid remain.
+            & $pruneNativeDir (Join-Path $Target '.agent\agents')
             & $pruneNativeDir (Join-Path $Target '.agent\skills')
             & $pruneAidSubtree (Join-Path $Target '.agent\aid')
         }
@@ -1267,6 +1342,140 @@ function Invoke-PruneToolDirs {
     }
 }
 
+# ---------------------------------------------------------------------------
+# Retired-root migration sweep (FR7/FR7a)
+# ---------------------------------------------------------------------------
+
+# Invoke-MigrateRetiredLayout <target> <tool> [aidVerbose]
+#
+# Complete-replacement migration: removes AID-owned content from the static
+# list of retired AID roots that no longer exist in the new bundle layout.
+# Called from Install-AidTool BEFORE Invoke-PruneToolDirs (same aid update pass).
+#
+# Retired roots swept per tool:
+#   codex:       .agents\                     (split layout retired)
+#   cursor:      .cursor\rules\               (rules dir retired)
+#   antigravity: .agent\rules\                (rules dir retired)
+#
+# Ownership markers applied (content-isolation.md rules 1+2):
+#   Marker 1: filename starts with "aid-" (tool-native dir files)
+#   Marker 2: lives inside an "aid\" subtree
+#
+# Marker 3 (AID:BEGIN/END region in root files) is NOT touched here;
+# that is handled by Copy-RootAgentFile exclusively.
+#
+# User content (no marker) is NEVER removed.
+# Idempotent: a no-op when the retired path is already absent.
+# Sets $script:_MigrateRetiredCount with the count of items removed.
+function Invoke-MigrateRetiredLayout {
+    param(
+        [string]$Target,
+        [string]$Tool,
+        [bool]$AidVerbose = $false,
+        [bool]$ListOnly = $false   # $true = dry-run enumeration only (no removals)
+    )
+
+    $script:_MigrateRetiredCount = 0
+
+    # Determine whether a file is AID-owned (markers 1 or 2).
+    $isAidOwned = {
+        param([System.IO.FileInfo]$File)
+        # Marker 1: filename starts with "aid-".
+        if ($File.Name -like 'aid-*') { return $true }
+        # Marker 2: lives inside an "aid" folder (any ancestor named "aid").
+        $dir = $File.Directory
+        while ($dir -ne $null -and $dir.FullName -ne $Target -and $dir.FullName -ne $dir.Root.FullName) {
+            if ($dir.Name -eq 'aid') { return $true }
+            $dir = $dir.Parent
+        }
+        return $false
+    }
+
+    # Sweep one retired root directory: move AID-owned files to trash, prune empty
+    # dirs, then remove the retired root itself if now empty.
+    # In ListOnly mode: enumerate would-be-moved files, make no changes.
+    $sweepRetiredRoot = {
+        param([string]$RDir)
+        if (-not (Test-Path $RDir -PathType Container)) { return }
+
+        $trashBase = Join-Path $Target (Join-Path '.aid' '.trash')
+
+        # Walk all files; move (or collect) AID-owned ones.
+        $files = @(Get-ChildItem -LiteralPath $RDir -Recurse -File -ErrorAction SilentlyContinue |
+                   Sort-Object FullName)
+        foreach ($f in $files) {
+            if (& $isAidOwned $f) {
+                if ($ListOnly) {
+                    # Emit path via Write-Output so the caller can capture with $(...).
+                    Write-Output $f.FullName
+                    $script:_MigrateRetiredCount++
+                } else {
+                    # Compute relative path from $Target and move to trash.
+                    $rel = $f.FullName.Substring($Target.Length).TrimStart([char]'\', [char]'/')
+                    $dest = Join-Path $trashBase $rel
+                    $destDir = Split-Path $dest -Parent
+                    New-Item -ItemType Directory -Path $destDir -Force -ErrorAction SilentlyContinue | Out-Null
+                    Move-Item -LiteralPath $f.FullName -Destination $dest -Force -ErrorAction SilentlyContinue
+                    $script:_MigrateRetiredCount++
+                    if ($AidVerbose) { Write-Host "Trashed: $($f.FullName) -> $dest" }
+                }
+            }
+        }
+
+        if ($ListOnly) { return }
+
+        # Prune now-empty subdirs (deepest first).
+        $subdirs = @(Get-ChildItem -LiteralPath $RDir -Recurse -Directory -ErrorAction SilentlyContinue)
+        # Guard: pipeline over an empty @() returns $null on PowerShell; [System.Array]::Sort($null)
+        # throws "Value cannot be null" when the retired root has no subdirectories (e.g. cursor
+        # .cursor/rules/ contains only files, no nested dirs; or on idempotent re-run when the dir
+        # is already absent). Mirrors bash rm -rf / rmdir which silently no-op on absent paths.
+        if ($subdirs.Count -gt 0) {
+            $subPaths = [string[]]($subdirs | ForEach-Object { $_.FullName })
+            [System.Array]::Sort($subPaths, [System.StringComparer]::Ordinal)
+            [System.Array]::Reverse($subPaths)
+            foreach ($dp in $subPaths) {
+                if (Test-Path $dp -PathType Container) {
+                    $rem = @(Get-ChildItem -LiteralPath $dp -ErrorAction SilentlyContinue) | Select-Object -First 1
+                    if (-not $rem) {
+                        Remove-Item -LiteralPath $dp -Force -ErrorAction SilentlyContinue
+                        if ($AidVerbose) { Write-Host "Retired dir: $dp" }
+                    }
+                }
+            }
+        }
+
+        # Remove the retired root itself if now empty.
+        if (Test-Path $RDir -PathType Container) {
+            $rem = @(Get-ChildItem -LiteralPath $RDir -ErrorAction SilentlyContinue) | Select-Object -First 1
+            if (-not $rem) {
+                Remove-Item -LiteralPath $RDir -Force -ErrorAction SilentlyContinue
+                if ($AidVerbose) { Write-Host "Retired root dir: $RDir" }
+            }
+        }
+    }
+
+    switch ($Tool) {
+        'codex' {
+            # Retired root: .agents\ (old split layout -- skills\ + aid\ lived here).
+            & $sweepRetiredRoot (Join-Path $Target '.agents')
+        }
+        'cursor' {
+            # Retired root: .cursor\rules\ (rules dir no longer in new layout).
+            & $sweepRetiredRoot (Join-Path $Target '.cursor\rules')
+        }
+        'antigravity' {
+            # Retired root: .agent\rules\ (rules dir no longer in new layout).
+            & $sweepRetiredRoot (Join-Path $Target '.agent\rules')
+        }
+        # claude-code and copilot-cli have no retired roots in this migration.
+    }
+
+    if (-not $ListOnly -and $script:_MigrateRetiredCount -gt 0) {
+        Write-Host "  $($script:_MigrateRetiredCount) retired AID file(s) moved to .aid/.trash/"
+    }
+}
+
 # ---------------------------------------------------------------------------
 # Version marker
 # ---------------------------------------------------------------------------
@@ -1284,6 +1493,118 @@ function Write-VersionMarker {
     [System.IO.File]::WriteAllBytes($markerPath, $bytes)
 }
 
+# ---------------------------------------------------------------------------
+# Project-level provisioning (work-007): required runtime file + VCS hygiene.
+# Parity with bash seed_settings_yml / update_gitignore. Both idempotent.
+# ---------------------------------------------------------------------------
+
+# AID-managed .gitignore region markers (must match the bash _AID_GI_* strings).
+$script:_AidGiBegin = "# >>> AID managed -- do not edit (aid add/update maintains this block) >>>"
+$script:_AidGiEnd   = "# <<< AID managed <<<"
+
+# Get-AidGitignoreBlock - return the AID-managed block as a single LF-joined
+# string (markers inclusive), NO trailing newline (matches bash contract).
+function script:Get-AidGitignoreBlock {
+    $lines = @(
+        $script:_AidGiBegin,
+        ".aid/.temp/",
+        ".aid/.trash/",
+        ".aid/.heartbeat/",
+        ".aid/generated/",
+        ".aid/knowledge/.cache/",
+        ".aid/knowledge/.manual-checklist.json",
+        ".aid/knowledge/.spot-check-facts.txt",
+        $script:_AidGiEnd
+    )
+    return ($lines -join "`n")
+}
+
+# Initialize-AidSettingsFile <target> <tool>
+# Seed <target>\.aid\settings.yml from the tool's just-installed template when it
+# does not already exist. NEVER overwrites existing settings.yml (user config).
+# Not manifest-tracked. Sets $script:_SeededSettings.
+function script:Initialize-AidSettingsFile {
+    param([string]$Target, [string]$Tool)
+    $script:_SeededSettings = $false
+    $root = script:Get-RootDir -Tool $Tool
+    if (-not $root) { return }
+    $aidDir = Join-Path $Target '.aid'
+    $dst  = Join-Path $aidDir 'settings.yml'
+    $tmpl = Join-Path (Join-Path (Join-Path (Join-Path $Target $root) 'aid') 'templates') 'settings.yml'
+    if (Test-Path $dst -PathType Leaf) { return }          # never clobber user config
+    # Template absent -> surface it (work-007 C5): a silent skip re-triggers the
+    # "no settings.yml" class and the format gate would then warn forever.
+    if (-not (Test-Path $tmpl -PathType Leaf)) {
+        [Console]::Error.WriteLine("WARN: AidInstallCore: settings template missing ($tmpl); .aid/settings.yml not seeded for '$Tool'.")
+        return
+    }
+    if (-not (Test-Path $aidDir -PathType Container)) {
+        New-Item -ItemType Directory -Path $aidDir -Force | Out-Null
+    }
+    # Seed from template, STAMPING format_version as the first line if absent, so
+    # the settings-format gate stays quiet. Byte-faithful (raw-byte prepend, no
+    # text round-trip) so the install tree is byte-identical to the bash seed
+    # (test-install-parity.sh diff -r covers .aid/settings.yml).
+    $tmplBytes = [System.IO.File]::ReadAllBytes($tmpl)
+    $tmplText  = [System.Text.Encoding]::UTF8.GetString($tmplBytes)
+    if ($tmplText -match '(?m)^format_version:') {
+        [System.IO.File]::WriteAllBytes($dst, $tmplBytes)
+    } else {
+        $fv = [System.Text.Encoding]::UTF8.GetBytes("format_version: $($script:_AidSupportedFormat)`n")
+        [System.IO.File]::WriteAllBytes($dst, [byte[]]($fv + $tmplBytes))
+    }
+    $script:_SeededSettings = $true
+}
+
+# Update-AidGitignore <target>
+# Ensure <target>\.gitignore carries the AID-managed region with the current
+# transient .aid/ exclusions. Creates if absent; else strips any existing AID
+# region, preserves user content, appends a fresh region with a single blank-line
+# separator. Idempotent. Sets $script:_GitignoreAction to created|updated|unchanged.
+function script:Update-AidGitignore {
+    param([string]$Target)
+    $script:_GitignoreAction = 'unchanged'
+    $gi = Join-Path $Target '.gitignore'
+    $block = script:Get-AidGitignoreBlock
+
+    if (-not (Test-Path $gi -PathType Leaf)) {
+        [System.IO.File]::WriteAllText($gi, $block + "`n", [System.Text.UTF8Encoding]::new($false))
+        $script:_GitignoreAction = 'created'
+        return
+    }
+
+    $existing = [System.IO.File]::ReadAllText($gi)
+    $normalized = ($existing -replace "`r`n", "`n") -replace "`r", "`n"
+    $srcLines = $normalized -split "`n"
+
+    # Strip any existing AID region.
+    $kept = [System.Collections.Generic.List[string]]::new()
+    $inBlk = $false
+    foreach ($ln in $srcLines) {
+        if ($ln -eq $script:_AidGiBegin) { $inBlk = $true; continue }
+        if ($inBlk -and $ln -eq $script:_AidGiEnd) { $inBlk = $false; continue }
+        if ($inBlk) { continue }
+        $kept.Add($ln)
+    }
+    # Trim trailing blank lines.
+    while ($kept.Count -gt 0 -and $kept[$kept.Count - 1] -match '^[ \t]*$') {
+        $kept.RemoveAt($kept.Count - 1)
+    }
+
+    $sb = [System.Text.StringBuilder]::new()
+    foreach ($ln in $kept) { [void]$sb.Append($ln); [void]$sb.Append("`n") }
+    if ($kept.Count -gt 0) { [void]$sb.Append("`n") }
+    [void]$sb.Append($block); [void]$sb.Append("`n")
+    $newContent = $sb.ToString()
+
+    if ($newContent -eq $normalized) {
+        $script:_GitignoreAction = 'unchanged'
+    } else {
+        [System.IO.File]::WriteAllText($gi, $newContent, [System.Text.UTF8Encoding]::new($false))
+        $script:_GitignoreAction = 'updated'
+    }
+}
+
 # ---------------------------------------------------------------------------
 # High-level Install-AidTool
 # ---------------------------------------------------------------------------
@@ -1312,6 +1633,10 @@ function Install-AidTool {
     $script:_CopyCountUpToDate = 0
     $script:_CopyCountUpdated  = 0
     $script:_CopyCountSkipped  = 0
+    $script:_CopyCountFailed   = 0
+    # Reset project-provisioning state (work-007).
+    $script:_SeededSettings  = $false
+    $script:_GitignoreAction = 'unchanged'
 
     $rootAgentFile = script:Get-RootAgentFile -Tool $Tool
 
@@ -1339,16 +1664,13 @@ function Install-AidTool {
             }
         }
         'codex' {
+            # New unified layout: .codex\ only (agents, skills, aid all under .codex\).
+            # .agents\ is the RETIRED split layout -- handled by Invoke-MigrateRetiredLayout.
             $codexDir  = Join-Path $StagingDir '.codex'
-            $agentsDir = Join-Path $StagingDir '.agents'
             if (Test-Path $codexDir -PathType Container) {
                 Copy-AidDir -SrcDir $codexDir -DstDir (Join-Path $Target '.codex') -Force $Force -AidVerbose $AidVerbose
                 & $collectPaths $codexDir $StagingDir $installPaths
             }
-            if (Test-Path $agentsDir -PathType Container) {
-                Copy-AidDir -SrcDir $agentsDir -DstDir (Join-Path $Target '.agents') -Force $Force -AidVerbose $AidVerbose
-                & $collectPaths $agentsDir $StagingDir $installPaths
-            }
         }
         'cursor' {
             $cursorDir = Join-Path $StagingDir '.cursor'
@@ -1373,6 +1695,12 @@ function Install-AidTool {
         }
     }
 
+    # Abort loudly if any AID-owned file failed to copy -- do NOT proceed to
+    # write a manifest that records a partial install as success (work-007 C4).
+    if ($script:_CopyCountFailed -gt 0) {
+        throw "AidInstallCore: $($script:_CopyCountFailed) file(s) failed to copy for '$Tool'. Install aborted (incomplete)."
+    }
+
     # Handle root agent file via in-place region update (Pillar 3).
     $rootSrc = Join-Path $StagingDir $rootAgentFile
     $rootDst = Join-Path $Target $rootAgentFile
@@ -1389,10 +1717,33 @@ function Install-AidTool {
         $installPaths.Add($rootAgentFile)
     }
 
+    # Manifest-seam entry gate (PLAN risk #3, delivery-001->002 seam).
+    # Runs BEFORE Write-AidManifest so a contaminated bundle never writes to disk.
+    # Assert that the new bundle's path set does NOT contain any retired roots.
+    # If a retired path leaked into the new manifest, fail loudly -- do not prune
+    # against a contaminated manifest (content-isolation cornerstone).
+    $retiredRoots = @('.agents/', '.cursor/rules/', '.agent/rules/')
+    foreach ($rr in $retiredRoots) {
+        foreach ($p in $installPaths) {
+            $pNorm = $p -replace '\\', '/'
+            if ($pNorm.StartsWith($rr, [System.StringComparison]::Ordinal)) {
+                [Console]::Error.WriteLine("ERROR: aid-install-core: manifest-seam violation: retired root '$rr' leaked into the new bundle manifest (path: $p). Aborting install to protect user content.")
+                return 1
+            }
+        }
+    }
+
     # Write manifest (merge).
     Write-AidManifest -ManifestPath $manifest -Tool $Tool -Version $Version `
         -Paths @($installPaths) -RootEntries @($rootEntries)
 
+    # Retired-root migration sweep (FR7/FR7a).
+    # Remove AID-owned content from retired layout dirs BEFORE the normal prune,
+    # so that old .agents\, .cursor\rules\, .agent\rules\ trees are cleaned up.
+    # A non-zero rc from Install-AidTool is treated as a mid-commit failure (caller
+    # prints the "re-run to heal" message); this function returns 0 (WARN-not-fail).
+    Invoke-MigrateRetiredLayout -Target $Target -Tool $Tool -AidVerbose $AidVerbose
+
     # Prune stale AID-owned files (Pillar 2, R7).
     # Build a HashSet from the new manifest path set for O(1) lookup.
     $pruneSet = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::Ordinal)
@@ -1402,6 +1753,11 @@ function Install-AidTool {
     # Write version marker.
     Write-VersionMarker -Target $Target -Version $Version
 
+    # Project-level provisioning (work-007): seed required settings.yml and
+    # maintain the .gitignore AID region. Both idempotent; safe per-tool.
+    script:Initialize-AidSettingsFile -Target $Target -Tool $Tool
+    script:Update-AidGitignore -Target $Target
+
     # Print concise install summary (always shown; per-file lines only when AidVerbose).
     $totalFiles = $script:_CopyCountCopied + $script:_CopyCountUpToDate + $script:_CopyCountUpdated + $script:_CopyCountSkipped
     if ($totalFiles -gt 0) {
@@ -1418,6 +1774,13 @@ function Install-AidTool {
         }
     }
 
+    # Report project-level provisioning actions (work-007; always shown).
+    if ($script:_SeededSettings) { Write-Host "  Created .aid/settings.yml from template" }
+    switch ($script:_GitignoreAction) {
+        'created' { Write-Host "  Created .gitignore with AID exclusions" }
+        'updated' { Write-Host "  Updated .gitignore AID exclusions" }
+    }
+
     return 0
 }
 
@@ -1511,13 +1874,20 @@ function Uninstall-AidTool {
     # Remove this tool from manifest.
     Remove-ManifestTool -ManifestPath $ManifestPath -Tool $Tool
 
-    # If no manifest remains, remove version marker and .aid dir if empty.
+    # If no manifest remains (last tool removed), remove the AID-provisioned
+    # project files so a full uninstall leaves .aid/ clean (work-007).
     if (-not (Test-Path $ManifestPath -PathType Leaf)) {
         $aidMetaDir = [System.IO.Path]::GetDirectoryName($ManifestPath)
         $versionMarker = Join-Path $aidMetaDir '.aid-version'
         if (Test-Path $versionMarker -PathType Leaf) {
             Remove-Item -LiteralPath $versionMarker -Force
         }
+        # Remove the install-time-seeded settings.yml (symmetric with the seed).
+        # Only fires when NO tools remain; a partial uninstall keeps it.
+        $seededSettings = Join-Path $aidMetaDir 'settings.yml'
+        if (Test-Path $seededSettings -PathType Leaf) {
+            Remove-Item -LiteralPath $seededSettings -Force
+        }
         if (Test-Path $aidMetaDir -PathType Container) {
             $rem = Get-ChildItem -LiteralPath $aidMetaDir -Recurse -File -ErrorAction SilentlyContinue | Select-Object -First 1
             if (-not $rem) {
@@ -1547,7 +1917,12 @@ function Get-ManifestToolList {
         $data.tools.PSObject.Properties | ForEach-Object {
             $tid = $_.Name
             $t   = $_.Value
-            $ver = if ($t.version) { $t.version } else { '' }
+            # Guard all per-tool property accesses via PSObject.Properties['key'] first.
+            # Set-StrictMode -Version Latest (active in this module) throws
+            # PropertyNotFoundException when accessing a missing property directly
+            # (e.g. $t.root_agent_files on pre-work-005 manifests that lack it).
+            # PSObject.Properties['key'] returns $null safely for absent properties.
+            $ver = if ($t.PSObject.Properties['version']) { [string]$t.version } else { '' }
             # Determine root agent file for this tool.
             $rootAgent = switch ($tid) {
                 'claude-code' { 'CLAUDE.md' }
@@ -1555,9 +1930,10 @@ function Get-ManifestToolList {
             }
             # Read root agent status from manifest.
             $rootStatus = ''
-            if ($t.root_agent_files) {
-                foreach ($entry in $t.root_agent_files) {
-                    if ($entry.path -eq $rootAgent) {
+            $rafEntries = if ($t.PSObject.Properties['root_agent_files']) { $t.root_agent_files } else { $null }
+            if ($rafEntries) {
+                foreach ($entry in $rafEntries) {
+                    if ($entry.PSObject.Properties['path'] -and ($entry.path -eq $rootAgent)) {
                         $rootStatus = if ($entry.PSObject.Properties['status']) { $entry.status } else { 'owned' }
                         break
                     }
@@ -1761,7 +2137,7 @@ function Get-AidStatus {
     $aidVersion = ''
     try {
         $data = Get-Content -LiteralPath $manifest -Raw | ConvertFrom-Json
-        if ($data.aid_version) { $aidVersion = $data.aid_version }
+        if ($data.PSObject.Properties['aid_version'] -and $data.aid_version) { $aidVersion = $data.aid_version }
     } catch {}
 
     # Read CLI ref version from $env:AID_HOME/VERSION.