kushi-agents 4.4.3 → 4.7.4

package/plugin/skills/self-check/run.ps1

@@ -35,6 +35,51 @@ param(
 $ErrorActionPreference = "Stop"
 $findings = New-Object System.Collections.Generic.List[object]
 
+function Get-UserConfigRoot {
+    # Cross-platform: APPDATA-like location for the live Clawpilot install.
+    if ($IsWindows -or $env:OS -eq 'Windows_NT') { return $env:USERPROFILE }
+    if ($env:HOME) { return $env:HOME }
+    return [Environment]::GetFolderPath('UserProfile')
+}
+
+function Get-ProjectsRootFromYaml {
+    # Read projects_root: from a YAML file without a yaml dep. Tolerates quoted/unquoted values.
+    param([string]$YamlPath)
+    if (-not (Test-Path $YamlPath)) { return $null }
+    try {
+        $lines = Get-Content -Path $YamlPath -ErrorAction SilentlyContinue
+        foreach ($l in $lines) {
+            if ($l -match '^\s*projects_root\s*:\s*["'']?([^"''#]+?)["'']?\s*(?:#.*)?$') {
+                $val = $Matches[1].Trim()
+                if ($val) { return $val }
+            }
+        }
+    } catch {}
+    return $null
+}
+
+function Resolve-EngagementRoots {
+    # Returns the union of resolvable engagement roots, in priority order:
+    #   1. $env:KUSHI_ENGAGEMENT_ROOT
+    #   2. <repo-root>/.kushi/config/user/project-evidence.yml#projects_root
+    #   3. <user-config-root>/.copilot/m-skills/kushi/config/user/project-evidence.yml#projects_root
+    # If none resolve, returns an empty array. Self-check D13/D14 will skip cleanly on machines
+    # without an engagement root configured (e.g. CI, contributors who haven't run setup yet).
+    param([string]$RepoRoot)
+    $roots = New-Object System.Collections.Generic.List[string]
+    if ($env:KUSHI_ENGAGEMENT_ROOT -and (Test-Path $env:KUSHI_ENGAGEMENT_ROOT)) {
+        [void]$roots.Add($env:KUSHI_ENGAGEMENT_ROOT)
+    }
+    $workspaceCfg = Join-Path $RepoRoot '.kushi\config\user\project-evidence.yml'
+    $wsRoot = Get-ProjectsRootFromYaml -YamlPath $workspaceCfg
+    if ($wsRoot -and (Test-Path $wsRoot)) { [void]$roots.Add($wsRoot) }
+    $userBase = Get-UserConfigRoot
+    $liveCfg = Join-Path $userBase '.copilot\m-skills\kushi\config\user\project-evidence.yml'
+    $liveRoot = Get-ProjectsRootFromYaml -YamlPath $liveCfg
+    if ($liveRoot -and (Test-Path $liveRoot)) { [void]$roots.Add($liveRoot) }
+    return ($roots | Select-Object -Unique)
+}
+
 function Add-Finding {
     param($Code, $Surface, $Severity, $Message, $Fix, $File, $Line)
     $findings.Add([PSCustomObject]@{
@@ -127,7 +172,7 @@ foreach ($p in $promptFiles) {
 
 # === C5: instructions referenced somewhere ===
 foreach ($inst in $instructionFiles) {
-    $needle = $inst.Name  # e.g. workiq-first.instructions.md
+    $needle = $inst.Name  # e.g. workiq-only.instructions.md
     $referenced = $false
     foreach ($key in $mdText.Keys) {
         if ($key -eq $inst.FullName) { continue }
@@ -299,13 +344,13 @@ foreach ($name in $fdeSkills) {
     }
 }
 
-# === C12: pull-* skills must reference thoroughness-detector + evidence templates carry Validation block ===
+# === C12: pull-* skills must reference evidence-thoroughness (merged thoroughness-detector v4.4.9) ===
 foreach ($d in $skillDirs | Where-Object { $_.Name -like 'pull-*' }) {
     $f = Join-Path $d.FullName 'SKILL.md'
     $text = $mdText[$f]
     if (-not $text) { continue }
-    if ($text -notmatch 'thoroughness-detector\.instructions\.md') {
-        Add-Finding C12 'Thoroughness enforcement' 'warning' "Skill $($d.Name) doesn't reference thoroughness-detector.instructions.md" "Add 'runtime detector + auto-retry + paste-prompt per ``thoroughness-detector.instructions.md``' to the skill intro." $f 0
+    if ($text -notmatch 'evidence-thoroughness\.instructions\.md') {
+        Add-Finding C12 'Thoroughness enforcement' 'warning' "Skill $($d.Name) doesn't reference evidence-thoroughness.instructions.md" "Add 'runtime detector + auto-retry + paste-prompt per ``evidence-thoroughness.instructions.md``' to the skill intro." $f 0
     }
 }
 $evidenceTemplateDirs = @('templates\weekly','templates\snapshot')
@@ -317,17 +362,17 @@ foreach ($td in $evidenceTemplateDirs) {
         if ($nonEvidenceTemplates -contains $_.Name) { return }
         $tx = Get-Content -Raw $_.FullName
         if ($tx -notmatch '##\s+Validation') {
-            Add-Finding C12 'Thoroughness enforcement' 'warning' "Evidence template $($_.Name) is missing '## Validation' block" "Append a Validation checklist per thoroughness-detector.instructions.md so the skill can tick checks on write." $_.FullName 0
+            Add-Finding C12 'Thoroughness enforcement' 'warning' "Evidence template $($_.Name) is missing '## Validation' block" "Append a Validation checklist per evidence-thoroughness.instructions.md so the skill can tick checks on write." $_.FullName 0
         }
     }
 }
 $pasteTpl = Join-Path $pluginDir 'templates\paste-prompt.md'
 if (-not (Test-Path $pasteTpl)) {
-    Add-Finding C12 'Thoroughness enforcement' 'warning' "plugin/templates/paste-prompt.md is missing" "Create the paste-prompt template referenced by thoroughness-detector.instructions.md." $pluginDir 0
+    Add-Finding C12 'Thoroughness enforcement' 'warning' "plugin/templates/paste-prompt.md is missing" "Create the paste-prompt template referenced by evidence-thoroughness.instructions.md." $pluginDir 0
 }
-$detectorFile = Join-Path $pluginDir 'instructions\thoroughness-detector.instructions.md'
+$detectorFile = Join-Path $pluginDir 'instructions\evidence-thoroughness.instructions.md'
 if (-not (Test-Path $detectorFile)) {
-    Add-Finding C12 'Thoroughness enforcement' 'warning' "plugin/instructions/thoroughness-detector.instructions.md is missing" "Create the detector instructions file — pull-* skills cite it." $pluginDir 0
+    Add-Finding C12 'Thoroughness enforcement' 'warning' "plugin/instructions/evidence-thoroughness.instructions.md is missing" "Create the detector instructions file — pull-* skills cite it." $pluginDir 0
 }
 
 # === Deep checks ===
@@ -533,13 +578,11 @@ if ($Deep) {
     if (-not (Test-Path $verbatimInst)) {
         Add-Finding D13 'Meetings verbatim doctrine' 'warning' "plugin/instructions/meetings-verbatim-required.instructions.md is missing" "Restore the meetings-verbatim-required instruction from kushi v3.10.0." $verbatimInst 0
     }
-    # Walk known engagement roots to find Evidence/*/meetings/stream/*.md files
-    $engagementRoots = @()
-    $envRoot = $env:KUSHI_ENGAGEMENT_ROOT
-    if ($envRoot -and (Test-Path $envRoot)) { $engagementRoots += $envRoot }
-    $defaultEngRoot = Join-Path $env:USERPROFILE 'OneDrive - Microsoft\ISE\Engagement Assets'
-    if (Test-Path $defaultEngRoot) { $engagementRoots += $defaultEngRoot }
-    foreach ($engRoot in ($engagementRoots | Select-Object -Unique)) {
+    # Walk known engagement roots to find Evidence/*/meetings/stream/*.md files.
+    # Resolution order: $env:KUSHI_ENGAGEMENT_ROOT → workspace .kushi config → live install config.
+    # No hardcoded personal paths.
+    $engagementRoots = Resolve-EngagementRoots -RepoRoot $Root
+    foreach ($engRoot in $engagementRoots) {
         $streamFiles = Get-ChildItem -Path $engRoot -Recurse -Filter '*_meetings-stream.md' -ErrorAction SilentlyContinue |
                        Where-Object { $_.FullName -match '\\Evidence\\[^\\]+\\(meetings|Meetings)\\stream\\' }
         foreach ($sf in $streamFiles) {
@@ -627,11 +670,9 @@ if ($Deep) {
         '_Weekly Summaries','_WeeklySummaries','weekly-summaries',
         'email','teams','meetings','onenote','sharepoint','crm','ado'
     )
-    $layoutEngRoots = @()
-    if ($env:KUSHI_ENGAGEMENT_ROOT -and (Test-Path $env:KUSHI_ENGAGEMENT_ROOT)) { $layoutEngRoots += $env:KUSHI_ENGAGEMENT_ROOT }
-    $layoutDefaultRoot = Join-Path $env:USERPROFILE 'OneDrive - Microsoft\ISE\Engagement Assets'
-    if (Test-Path $layoutDefaultRoot) { $layoutEngRoots += $layoutDefaultRoot }
-    foreach ($engRoot in ($layoutEngRoots | Select-Object -Unique)) {
+    # Engagement-root resolution (no hardcoded personal paths) — see Resolve-EngagementRoots.
+    $layoutEngRoots = Resolve-EngagementRoots -RepoRoot $Root
+    foreach ($engRoot in $layoutEngRoots) {
         $projectDirs = Get-ChildItem -Path $engRoot -Directory -ErrorAction SilentlyContinue |
                        Where-Object { Test-Path (Join-Path $_.FullName 'Evidence') }
         foreach ($pd in $projectDirs) {
@@ -678,6 +719,387 @@ if ($Deep) {
             Add-Finding D15 'Legacy paths' 'warning' $msg $fix $m.Path $m.LineNumber
         }
     }
+
+    # D16: cross-platform parity (Windows + macOS) — kushi v4.4.6+
+    # Contract: every contributor-facing install/setup surface must address BOTH Windows and macOS.
+    $d16Touchpoints = @(
+        @{ Path = 'plugin/skills/setup/SKILL.md'; MustContain = @('winget', 'brew install --cask'); Why = 'setup recovery prompts must include both Windows (winget) and macOS (brew) install paths' }
+        @{ Path = 'docs/getting-started/install-workiq.md'; MustContain = @('winget', 'brew', '### macOS'); Why = 'install-workiq doc must have explicit Windows + macOS sections' }
+        @{ Path = 'src/check-workiq.mjs'; MustContain = @("'win32'", "'darwin'"); Why = 'check-workiq must branch install hints by process.platform for Windows + macOS' }
+    )
+    foreach ($tp in $d16Touchpoints) {
+        $tpPath = Join-Path $Root $tp.Path
+        if (-not (Test-Path $tpPath)) {
+            Add-Finding D16 'Cross-platform parity' 'warning' "Required parity touchpoint missing: $($tp.Path)" "Create the file or update D16 in self-check if intentionally removed." $tpPath 0
+            continue
+        }
+        $body = Get-Content -Raw $tpPath
+        foreach ($needle in $tp.MustContain) {
+            if ($body -notmatch [regex]::Escape($needle)) {
+                Add-Finding D16 'Cross-platform parity' 'warning' "$($tp.Path) missing '$needle' — $($tp.Why)" "Add a macOS/Windows-branched block. Windows uses winget install Microsoft.WorkIQ; macOS uses brew install --cask microsoft-workiq + (optionally) brew install --cask powershell for pwsh." $tpPath 0
+            }
+        }
+    }
+    $shPath = Join-Path $Root 'plugin/skills/self-check/run.sh'
+    $ps1Path = Join-Path $Root 'plugin/skills/self-check/run.ps1'
+    if (-not (Test-Path $shPath)) {
+        Add-Finding D16 'Cross-platform parity' 'warning' "self-check is missing run.sh (macOS/Linux entrypoint)" "Restore plugin/skills/self-check/run.sh — pwsh-7 wrapper for non-Windows contributors." $shPath 0
+    }
+    if (-not (Test-Path $ps1Path)) {
+        Add-Finding D16 'Cross-platform parity' 'warning' "self-check is missing run.ps1 (Windows entrypoint)" "Restore plugin/skills/self-check/run.ps1." $ps1Path 0
+    }
+
+    # D17: fuzzy-disambiguation doctrine cited by skills that resolve names -> IDs (v4.4.7+)
+    $fuzzyInst = Join-Path $instructionsDir 'fuzzy-disambiguation.instructions.md'
+    if (-not (Test-Path $fuzzyInst)) {
+        Add-Finding D17 'Fuzzy disambiguation' 'warning' "plugin/instructions/fuzzy-disambiguation.instructions.md is missing" "Restore the v4.4.7 fuzzy doctrine." $fuzzyInst 0
+    } else {
+        $fuzzyCallers = @(
+            'pull-onenote','pull-sharepoint','pull-teams','pull-crm','pull-ado','pull-email',
+            'engagement-root-resolution.instructions.md','ask-project'
+        )
+        foreach ($caller in $fuzzyCallers) {
+            $candidate = if ($caller -like '*.instructions.md') {
+                Join-Path $instructionsDir $caller
+            } else {
+                Join-Path (Join-Path $skillsDir $caller) 'SKILL.md'
+            }
+            if (Test-Path $candidate) {
+                $body = Get-Content -Raw $candidate
+                if ($body -notmatch 'fuzzy-disambiguation\.instructions\.md') {
+                    Add-Finding D17 'Fuzzy disambiguation' 'warning' "$caller does not reference fuzzy-disambiguation.instructions.md" "Add a one-line cite: 'Name → ID resolution follows fuzzy-disambiguation.instructions.md (universal flow).' " $candidate 0
+                }
+            }
+        }
+    }
+
+    # D18: per-source-verification-gate cited by pull-* + orchestrators (v4.4.7+)
+    $gateInst = Join-Path $instructionsDir 'per-source-verification-gate.instructions.md'
+    if (-not (Test-Path $gateInst)) {
+        Add-Finding D18 'Verification gate' 'warning' "plugin/instructions/per-source-verification-gate.instructions.md is missing" "Restore the v4.4.7 verification-gate doctrine." $gateInst 0
+    } else {
+        $gateCallers = @('bootstrap-project','refresh-project','aggregate-project') + (Get-ChildItem $skillsDir -Directory | Where-Object { $_.Name -like 'pull-*' } | Select-Object -ExpandProperty Name)
+        foreach ($caller in $gateCallers) {
+            $sf = Join-Path (Join-Path $skillsDir $caller) 'SKILL.md'
+            if (Test-Path $sf) {
+                $body = Get-Content -Raw $sf
+                if ($body -notmatch 'per-source-verification-gate\.instructions\.md') {
+                    Add-Finding D18 'Verification gate' 'warning' "$caller/SKILL.md does not reference per-source-verification-gate.instructions.md" "Add a one-line cite in the front blockquote or References section." $sf 0
+                }
+            }
+        }
+    }
+
+    # D19: FOLLOW-UPS.md format compliance — when present, every Open entry has 5 required fields
+    $followUpsFiles = Get-ChildItem -Path $Root -Recurse -Filter 'FOLLOW-UPS.md' -ErrorAction SilentlyContinue | Where-Object { $_.FullName -notmatch '[\\/](node_modules|\.git|customer_docs)[\\/]' } -ErrorAction SilentlyContinue
+    foreach ($fu in $followUpsFiles) {
+        $body = Get-Content -Raw $fu.FullName
+        if ($body -match '## Open follow-ups([\s\S]*?)(##|\Z)') {
+            $openBlock = $Matches[1]
+            # Each ### sub-entry should mention the 5 anchors
+            $entries = [regex]::Matches($openBlock, '(?m)^### .+$')
+            foreach ($entry in $entries) {
+                $entryStart = $entry.Index + $entry.Length
+                $next = $openBlock.IndexOf("`n### ", $entryStart)
+                $entryEnd = if ($next -lt 0) { $openBlock.Length } else { $next }
+                $entryText = $openBlock.Substring($entryStart, $entryEnd - $entryStart)
+                $required = @('Gate failures','Next-time-do','Tracking','Run-log entry','Status')
+                foreach ($r in $required) {
+                    if ($entryText -notmatch [regex]::Escape($r)) {
+                        Add-Finding D19 'FOLLOW-UPS format' 'warning' "$($fu.FullName): an Open follow-up entry is missing the '$r' field" "Per per-source-verification-gate.instructions.md, every Open entry must have all 5 fields (Gate failures, Next-time-do, Tracking, Run-log entry, Status)." $fu.FullName 0
+                    }
+                }
+            }
+        }
+    }
+
+    # D20: README verbs table coverage — every prompt has a row + every row has a prompt
+    if (Test-Path $readmeFile) {
+        $readme = Get-Content -Raw $readmeFile
+        if ($readme -match '## Verbs\s*\r?\n([\s\S]*?)(?=\r?\n##\s)') {
+            $verbsBlock = $Matches[1]
+            # Verb rows: lines starting with | `verb`
+            $verbRowMatches = [regex]::Matches($verbsBlock, '\|\s*`([a-z0-9-]+)`')
+            $documentedVerbs = $verbRowMatches | ForEach-Object { $_.Groups[1].Value } | Sort-Object -Unique
+            $promptStems = $promptFiles | ForEach-Object { $_.BaseName -replace '\.prompt$','' }
+            foreach ($p in $promptStems) {
+                if ($documentedVerbs -notcontains $p) {
+                    Add-Finding D20 'README verbs coverage' 'warning' "Verb '$p' has a prompt file but no row in README ## Verbs table" "Add ``| ``$p`` | <profile> | <window> | <description> |`` to the README verbs table." $readmeFile 0
+                }
+            }
+            foreach ($v in $documentedVerbs) {
+                if ($promptStems -notcontains $v -and $v -notin @('setup','aggregate','bootstrap','refresh','state','consolidate','status','ask','propose-ado','apply-ado')) {
+                    # Already-aliased verbs are fine; only flag entries with no underlying prompt + no known alias.
+                    Add-Finding D20 'README verbs coverage' 'warning' "README ## Verbs row '$v' has no matching prompt file under plugin/prompts/" "Either rename the row to match an existing prompt or add plugin/prompts/$v.prompt.md." $readmeFile 0
+                }
+            }
+        } else {
+            Add-Finding D20 'README verbs coverage' 'warning' "README.md is missing a '## Verbs' section" "Add the Verbs table per the skill coverage doctrine — every plugin/prompts/<verb>.prompt.md must have a row." $readmeFile 0
+        }
+    }
+
+    # D21: pwsh-friendly scripts — every .ps1 in the repo must be runnable on pwsh 7 cross-platform
+    # Heuristic: flag any .ps1 that uses Windows-only APIs (Get-CimInstance Win32_*, [Environment]::SpecialFolder.Desktop, registry, com objects, Get-WmiObject)
+    $crossPlatScripts = Get-ChildItem -Path $Root -Recurse -Include '*.ps1' -ErrorAction SilentlyContinue | Where-Object { $_.FullName -notmatch '[\\/]node_modules[\\/]' }
+    $winOnlyPatterns = @(
+        @{ Pattern = 'Get-WmiObject'; Hint = 'use Get-CimInstance (cross-platform) or remove' }
+        @{ Pattern = 'Win32_'; Hint = 'WMI/CIM Win32_* classes are Windows-only — gate with if ($IsWindows)' }
+        @{ Pattern = 'New-Object -ComObject'; Hint = 'COM is Windows-only — gate with if ($IsWindows)' }
+        @{ Pattern = 'Get-ItemProperty -Path HK'; Hint = 'registry access is Windows-only — gate with if ($IsWindows)' }
+    )
+    foreach ($s in $crossPlatScripts) {
+        $body = Get-Content -Raw $s.FullName
+        foreach ($p in $winOnlyPatterns) {
+            if ($body -match [regex]::Escape($p.Pattern)) {
+                if ($body -notmatch '\$IsWindows') {
+                    Add-Finding D21 'Cross-platform scripts' 'warning' "$($s.FullName -replace [regex]::Escape($Root),'') uses Windows-only API '$($p.Pattern)' without an `$IsWindows` guard" "Gate the call with ``if (`$IsWindows) { ... }`` so the script works on macOS/Linux contributors. $($p.Hint)" $s.FullName 0
+                }
+            }
+        }
+    }
+
+    # D22: Duplicate / overlap detection — flag instruction files whose description frontmatter overlaps too much
+    $instFilesD22 = Get-ChildItem $instructionsDir -Filter '*.instructions.md' -ErrorAction SilentlyContinue
+    $instDescs = @{}
+    foreach ($inst in $instFilesD22) {
+        $body = Get-Content -Raw $inst.FullName
+        if ($body -match '(?ms)^---.*?description:\s*"([^"]+)".*?---') {
+            $desc = $Matches[1].ToLower()
+            # Tokenize — keep word stems > 4 chars
+            $tokens = ([regex]::Matches($desc, '[a-z]{5,}') | ForEach-Object { $_.Value }) | Sort-Object -Unique
+            $instDescs[$inst.Name] = $tokens
+        }
+    }
+    $instNames = @($instDescs.Keys)
+    for ($i = 0; $i -lt $instNames.Count; $i++) {
+        for ($j = $i+1; $j -lt $instNames.Count; $j++) {
+            $a = $instNames[$i]; $b = $instNames[$j]
+            $tokA = $instDescs[$a]; $tokB = $instDescs[$b]
+            if ($tokA.Count -lt 4 -or $tokB.Count -lt 4) { continue }
+            $shared = @($tokA | Where-Object { $tokB -contains $_ }).Count
+            $minLen = [Math]::Min($tokA.Count, $tokB.Count)
+            $overlap = if ($minLen -gt 0) { $shared / $minLen } else { 0 }
+            if ($overlap -ge 0.6) {
+                Add-Finding D22 'Duplicate detection' 'warning' "Instructions $a and $b have $([math]::Round($overlap*100))% description-word overlap" "Read both — consider merging into one file, or add a clarifying scope line to each so callers can distinguish them. See docs/reference/instructions-map.md for current categorization." (Join-Path $instructionsDir $a) 0
+            }
+        }
+    }
+
+    # D23: instructions-map.md parity — every instruction file is listed in the map
+    $mapFile = Join-Path $Root 'docs\reference\instructions-map.md'
+    if (-not (Test-Path $mapFile)) {
+        Add-Finding D23 'Instructions map' 'warning' "docs/reference/instructions-map.md is missing" "Generate the map: lists every plugin/instructions/*.instructions.md by category with caller counts." $mapFile 0
+    } else {
+        $mapBody = Get-Content -Raw $mapFile
+        foreach ($inst in $instFilesD22) {
+            $stem = $inst.Name -replace '\.instructions\.md$',''
+            # Check for the stem mentioned anywhere in the map (as `stem` or in a table cell)
+            if ($mapBody -notmatch [regex]::Escape($stem)) {
+                Add-Finding D23 'Instructions map' 'warning' "Instruction '$stem' is not listed in docs/reference/instructions-map.md" "Regenerate the map (every plugin/instructions/*.instructions.md must appear in a category table + the Callers section)." $mapFile 0
+            }
+        }
+        # Reverse: every stem mentioned in the map exists on disk
+        $mapStems = [regex]::Matches($mapBody, '\| \x60([a-z0-9-]+)\x60 \|') | ForEach-Object { $_.Groups[1].Value } | Sort-Object -Unique
+        foreach ($s in $mapStems) {
+            $expected = Join-Path $instructionsDir "$s.instructions.md"
+            if (-not (Test-Path $expected)) {
+                Add-Finding D23 'Instructions map' 'warning' "instructions-map.md lists '$s' but plugin/instructions/$s.instructions.md does not exist" "Remove the row from instructions-map.md (and verify no caller still references the deleted instruction)." $mapFile 0
+            }
+        }
+    }
+
+    # D24: OneDrive pin policy applicable but own evidence appears cloud-only
+    # Only meaningful on a real machine — we look at the live config, not the repo.
+    $userCfg = Join-Path $env:USERPROFILE '.copilot\m-skills\kushi\config\user\project-evidence.yml'
+    if (Test-Path $userCfg) {
+        $cfgText = Get-Content -Raw $userCfg
+        $projectsRoot = $null
+        $myAlias = $null
+        if ($cfgText -match '(?m)^\s*projects_root:\s*"?([^"\r\n]+)"?') { $projectsRoot = $Matches[1].Trim() }
+        if ($cfgText -match '(?m)^\s*alias:\s*"?([^"\r\n]+)"?') { $myAlias = $Matches[1].Trim() }
+        if ($projectsRoot -and $myAlias -and (Test-Path $projectsRoot)) {
+            $inOD = $false
+            if ($IsWindows -or $env:OS -eq 'Windows_NT') {
+                if ($projectsRoot -like (Join-Path $env:USERPROFILE '*')) { $inOD = $true }
+            } else {
+                if ($projectsRoot -like "$env:HOME/Library/CloudStorage/*" -or $projectsRoot -like "$env:HOME/OneDrive*") { $inOD = $true }
+            }
+            if ($inOD) {
+                Get-ChildItem -Directory $projectsRoot -ErrorAction SilentlyContinue | ForEach-Object {
+                    $myEv = Join-Path $_.FullName "Evidence/$myAlias"
+                    if (Test-Path $myEv) {
+                        if ($IsWindows -or $env:OS -eq 'Windows_NT') {
+                            $attr = (& attrib $myEv 2>$null) -join ''
+                            if ($attr -match '\bU\b' -and $attr -notmatch '\bP\b') {
+                                Add-Finding D24 'OneDrive pin' 'warning' "Own evidence folder $myEv is cloud-only (U set, P not set) — may slow writes during refresh" "Re-run '@Kushi setup --reconfigure' to re-apply pin policy, or right-click the folder in Explorer -> 'Always keep on device'. See docs/concepts/sync-and-pinning.md." $myEv 0
+                            }
+                        } else {
+                            $pinned = (& xattr -p com.microsoft.OneDrive.PinnedToDevice $myEv 2>$null)
+                            if (-not $pinned) {
+                                Add-Finding D24 'OneDrive pin' 'warning' "Own evidence folder $myEv is not pinned — may slow writes during refresh" "Re-run '@Kushi setup --reconfigure' to re-apply pin policy, or run: xattr -w com.microsoft.OneDrive.PinnedToDevice 1 '$myEv'. See docs/concepts/sync-and-pinning.md." $myEv 0
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    # D25: Documentation coverage — every instructions file is referenced from at least one user-facing doc
+    $docFiles = @()
+    $docFiles += Get-ChildItem (Join-Path $Root 'docs') -Recurse -Filter '*.md' -ErrorAction SilentlyContinue
+    $changelogFile = Join-Path $Root 'CHANGELOG.md'
+    if (Test-Path $changelogFile) { $docFiles += Get-Item $changelogFile }
+    $docCorpus = ''
+    foreach ($d in $docFiles) {
+        if ($d.FullName -eq (Join-Path $Root 'docs\reference\instructions-map.md')) { continue }  # D23 already checks this
+        try { $docCorpus += [string](Get-Content -Raw $d.FullName) + "`n" } catch {}
+    }
+    foreach ($inst in $instFilesD22) {
+        $stem = $inst.Name -replace '\.instructions\.md$',''
+        if ($docCorpus -notmatch [regex]::Escape($stem)) {
+            Add-Finding D25 'Documentation coverage' 'warning' "Instruction '$stem' is not mentioned in CHANGELOG.md or any docs/concepts|reference|how-to doc" "Add a one-line CHANGELOG entry for the release that introduced it AND either (a) extend an existing doc to mention it, or (b) add a new doc under docs/concepts/ or docs/how-to/. See docs/concepts/sync-and-pinning.md for the v4.5.0 example." (Join-Path $instructionsDir $inst.Name) 0
+        }
+    }
+
+    # D26: Issue Recovery Rule cite — every skill that hits an external service OR consumes its evidence MUST cite issue-recovery.instructions.md.
+    $issueRecInst = Join-Path $instructionsDir 'issue-recovery.instructions.md'
+    if (-not (Test-Path $issueRecInst)) {
+        Add-Finding D26 'Issue Recovery cite' 'warning' "plugin/instructions/issue-recovery.instructions.md is missing" "Restore the Issue Recovery doctrine from kushi v4.5.1." $issueRecInst 0
+    } else {
+        $recoveryRequired = @(
+            'pull-email','pull-teams','pull-meetings','pull-onenote','pull-loop','pull-sharepoint',
+            'pull-crm','pull-ado','pull-misc',
+            'aggregate-project','consolidate-evidence',
+            'bootstrap-project','refresh-project',
+            'apply-ado-update','propose-ado-update'
+        )
+        foreach ($skillName in $recoveryRequired) {
+            $skillFile = Join-Path $skillsDir "$skillName\SKILL.md"
+            if (-not (Test-Path $skillFile)) { continue }
+            $txt = $mdText[$skillFile]
+            if (-not $txt) { try { $txt = Get-Content -Raw $skillFile } catch { $txt = '' } }
+            if ($txt -notmatch 'issue-recovery') {
+                Add-Finding D26 'Issue Recovery cite' 'warning' "Skill '$skillName' does not cite issue-recovery.instructions.md" "Add a 'References' bullet linking to ../../instructions/issue-recovery.instructions.md so the Issue Recovery Rule applies when external service failures expose doctrine gaps." $skillFile 0
+            }
+        }
+    }
+
+    # D27: Personal-path leakage — no contributor-specific paths committed to plugin/ or docs/getting-started/.
+    # The repo is shared across contributors and across OSes. Examples must use placeholders.
+    $personalPatterns = @(
+        @{ Pattern = 'OneDrive - Microsoft\\ISE\\Engagement Assets'; Hint = "Use placeholder '<engagement-root>' or '`$env:KUSHI_ENGAGEMENT_ROOT'." },
+        @{ Pattern = 'C:\\Users\\ushak';                              Hint = "Use placeholder '<your-home>' or '`$env:USERPROFILE'." },
+        @{ Pattern = 'C:\\Usha\\ISERepos\\kushi';                     Hint = "Use placeholder '<kushi-repo-root>' or relative path." },
+        @{ Pattern = 'ushak@microsoft\.com';                          Hint = "Use placeholder '<your-email>' or 'you@example.com'." }
+    )
+    $leakTargets = @(
+        (Join-Path $Root 'plugin'),
+        (Join-Path $Root 'docs\getting-started'),
+        (Join-Path $Root 'README.md')
+    )
+    # Exempt files: CHANGELOG, learnings (history), example outputs explicitly marked as sample
+    $leakExempt = @(
+        'CHANGELOG.md', 'plugin\learnings', 'plugin\reference-packs',
+        'plugin\skills\self-check'
+    )
+    foreach ($target in $leakTargets) {
+        if (-not (Test-Path $target)) { continue }
+        $leakFiles = if ((Get-Item $target).PSIsContainer) {
+            Get-ChildItem -Path $target -Recurse -File -Include '*.md','*.ps1','*.mjs','*.json','*.yml','*.yaml' -ErrorAction SilentlyContinue
+        } else { @(Get-Item $target) }
+        foreach ($f in $leakFiles) {
+            $skip = $false
+            foreach ($ex in $leakExempt) { if ($f.FullName -like "*$ex*") { $skip = $true; break } }
+            if ($skip) { continue }
+            $content = $null
+            try { $content = Get-Content -Raw $f.FullName } catch { continue }
+            if (-not $content) { continue }
+            foreach ($p in $personalPatterns) {
+                if ($content -match $p.Pattern) {
+                    $rel = $f.FullName -replace [regex]::Escape($Root + '\'),''
+                    Add-Finding D27 'Personal-path leakage' 'warning' "$rel contains personal path/email pattern '$($p.Pattern)'" $p.Hint $f.FullName 0
+                }
+            }
+        }
+    }
+
+    # D28: Predecessor-agent leakage — kushi documentation should not reference predecessor agents by name.
+    # The historical predecessor was an internal agent ("nova"); current docs must use neutral language so
+    # documentation stays portable. Exemptions: CHANGELOG.md (historical commit notes), plugin/learnings (records
+    # of past defects), plugin/reference-packs (bundled doctrine that may legitimately reference predecessors).
+    $leakageWord = 'nova'
+    $novaTargets = @(
+        (Join-Path $Root 'plugin'),
+        (Join-Path $Root 'docs')
+    )
+    $novaExempt = @(
+        'CHANGELOG.md', 'plugin\learnings', 'plugin\reference-packs', 'docs\reference\instructions-map.md',
+        'plugin\skills\self-check'
+    )
+    foreach ($target in $novaTargets) {
+        if (-not (Test-Path $target)) { continue }
+        $novaFiles = Get-ChildItem -Path $target -Recurse -File -Include '*.md','*.ps1','*.mjs','*.json','*.yml','*.yaml' -ErrorAction SilentlyContinue
+        foreach ($f in $novaFiles) {
+            $skip = $false
+            foreach ($ex in $novaExempt) { if ($f.FullName -like "*$ex*") { $skip = $true; break } }
+            if ($skip) { continue }
+            $content = $null
+            try { $content = Get-Content -Raw $f.FullName } catch { continue }
+            if (-not $content) { continue }
+            # Match standalone word 'nova' (case-insensitive), not 'innovation' / 'novanet' etc.
+            if ($content -match '(?i)\bnova\b') {
+                $rel = $f.FullName -replace [regex]::Escape($Root + '\'),''
+                Add-Finding D28 'Predecessor-agent leakage' 'warning' "$rel references predecessor agent by name" "Replace with neutral language ('predecessor agent' / 'another internal agent') or remove the reference. Exemptions live in CHANGELOG.md and plugin/learnings/." $f.FullName 0
+            }
+        }
+    }
+
+    # D29: Vertex integration integrity — validate studios.json, verify detect/validate libs parse,
+    # verify emit-vertex / vertex-link skill files reference only in-place vertex paths (no vendored schema folder).
+    $studiosJson = Join-Path $Root 'plugin\config\studios.json'
+    $studiosSchema = Join-Path $Root 'plugin\config\studios.schema.json'
+    if (-not (Test-Path $studiosJson)) {
+        Add-Finding D29 'Vertex integration integrity' 'error' 'plugin/config/studios.json missing' 'Restore the studio registry packaged file.' $studiosJson 0
+    } elseif (-not (Test-Path $studiosSchema)) {
+        Add-Finding D29 'Vertex integration integrity' 'error' 'plugin/config/studios.schema.json missing' 'Restore the studio registry schema.' $studiosSchema 0
+    } else {
+        try { $null = Get-Content -Raw $studiosJson | ConvertFrom-Json } catch {
+            Add-Finding D29 'Vertex integration integrity' 'error' 'plugin/config/studios.json is not valid JSON' $_.Exception.Message $studiosJson 0
+        }
+        try { $null = Get-Content -Raw $studiosSchema | ConvertFrom-Json } catch {
+            Add-Finding D29 'Vertex integration integrity' 'error' 'plugin/config/studios.schema.json is not valid JSON' $_.Exception.Message $studiosSchema 0
+        }
+    }
+
+    $detectLib = Join-Path $Root 'plugin\lib\detect-vertex-repo.mjs'
+    $validateLib = Join-Path $Root 'plugin\lib\vertex-validate.mjs'
+    foreach ($lib in @($detectLib, $validateLib)) {
+        if (-not (Test-Path $lib)) {
+            Add-Finding D29 'Vertex integration integrity' 'error' "$([System.IO.Path]::GetFileName($lib)) missing in plugin/lib/" 'Restore the helper module.' $lib 0
+        } else {
+            $node = Get-Command node -ErrorAction SilentlyContinue
+            if ($node) {
+                $check = & node --check $lib 2>&1
+                if ($LASTEXITCODE -ne 0) {
+                    Add-Finding D29 'Vertex integration integrity' 'error' "$([System.IO.Path]::GetFileName($lib)) failed node --check" "$check" $lib 0
+                }
+            }
+        }
+    }
+
+    # Detect-don't-vendor invariant: ensure no plugin/templates/vertex-schemas/ exists.
+    $vendoredSchemas = Join-Path $Root 'plugin\templates\vertex-schemas'
+    if (Test-Path $vendoredSchemas) {
+        Add-Finding D29 'Vertex integration integrity' 'error' 'plugin/templates/vertex-schemas/ exists — vertex schemas must not be vendored' 'Delete plugin/templates/vertex-schemas/. Schemas are detected in place from the configured vertex repo via vertex.json + .vertex/scripts/validation/.' $vendoredSchemas 0
+    }
+
+    foreach ($s in @('emit-vertex','vertex-link')) {
+        $skillPath = Join-Path $Root "plugin\skills\$s\SKILL.md"
+        if (-not (Test-Path $skillPath)) {
+            Add-Finding D29 'Vertex integration integrity' 'error' "plugin/skills/$s/SKILL.md missing" 'The vertex integration skills must ship with the package.' $skillPath 0
+        }
+    }
 }
 
 # === Output ===