kushi-agents 3.4.1

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

@@ -0,0 +1,517 @@
+<#
+.SYNOPSIS
+Kushi self-check — validates docs/skill consistency against the file system.
+
+.DESCRIPTION
+Source of truth is plugin/skills/. Reports gaps as warnings with concrete fixes.
+Returns exit code 0 always (warnings don't fail the run); use -StrictExit to flip
+that behaviour for CI.
+
+.PARAMETER Root
+Repo root (default: two levels above this script — i.e. kushi repo root).
+
+.PARAMETER Deep
+Also run D-checks (template references, snapshot/stream, WorkIQ hygiene, live install sync).
+
+.PARAMETER Json
+Emit findings as JSON (for CI / agent consumption) instead of human prose.
+
+.PARAMETER StrictExit
+Exit with code 1 if any findings are produced.
+
+.EXAMPLE
+pwsh plugin/skills/self-check/run.ps1
+pwsh plugin/skills/self-check/run.ps1 -Deep
+pwsh plugin/skills/self-check/run.ps1 -Deep -Json | ConvertFrom-Json
+#>
+[CmdletBinding()]
+param(
+    [string]$Root = (Resolve-Path (Join-Path $PSScriptRoot "..\..\..")).Path,
+    [switch]$Deep,
+    [switch]$Json,
+    [switch]$StrictExit
+)
+
+$ErrorActionPreference = "Stop"
+$findings = New-Object System.Collections.Generic.List[object]
+
+function Add-Finding {
+    param($Code, $Surface, $Severity, $Message, $Fix, $File, $Line)
+    $findings.Add([PSCustomObject]@{
+        code = $Code; surface = $Surface; severity = $Severity
+        message = $Message; fix = $Fix; file = $File; line = $Line
+    })
+}
+
+function Get-Frontmatter {
+    param([string]$Path)
+    $text = Get-Content -Raw -Path $Path
+    if ($text -notmatch '^(?s)---\r?\n(.*?)\r?\n---') { return @{} }
+    $yaml = $Matches[1]
+    $fm = @{}
+    foreach ($line in $yaml -split "`n") {
+        if ($line -match '^\s*([a-zA-Z0-9_-]+)\s*:\s*"?([^"]*?)"?\s*$') {
+            $fm[$Matches[1]] = $Matches[2]
+        }
+    }
+    return $fm
+}
+
+# === Discovery (source of truth) ===
+$pluginDir       = Join-Path $Root 'plugin'
+$skillsDir       = Join-Path $pluginDir 'skills'
+$instructionsDir = Join-Path $pluginDir 'instructions'
+$promptsDir      = Join-Path $pluginDir 'prompts'
+$agentFile       = Join-Path $pluginDir 'agents\kushi.agent.md'
+$readmeFile      = Join-Path $Root 'README.md'
+$wtlFile         = Join-Path $Root 'docs\reference\where-things-live.md'
+
+if (-not (Test-Path $pluginDir)) {
+    Write-Error "plugin/ not found at $pluginDir — run from kushi repo root or pass -Root."
+    exit 2
+}
+
+$skillDirs = Get-ChildItem $skillsDir -Directory | Sort-Object Name
+$skillNames = $skillDirs.Name
+$instructionFiles = Get-ChildItem $instructionsDir -Filter '*.instructions.md' -EA SilentlyContinue
+$promptFiles = Get-ChildItem $promptsDir -Filter '*.prompt.md' -EA SilentlyContinue
+
+# Pre-load text of all plugin md files for cross-reference scans
+$allMd = Get-ChildItem $pluginDir -Recurse -Filter '*.md'
+$mdText = @{}
+foreach ($f in $allMd) { $mdText[$f.FullName] = Get-Content -Raw -Path $f.FullName }
+
+# === C1, C2: frontmatter + name match ===
+foreach ($d in $skillDirs) {
+    $skillFile = Join-Path $d.FullName 'SKILL.md'
+    if (-not (Test-Path $skillFile)) {
+        Add-Finding C1 'Frontmatter' 'error' "Skill `"$($d.Name)`" has no SKILL.md" "Create plugin/skills/$($d.Name)/SKILL.md with name/version/description frontmatter." $d.FullName 0
+        continue
+    }
+    $fm = Get-Frontmatter $skillFile
+    foreach ($key in @('name','version','description')) {
+        if (-not $fm[$key]) {
+            Add-Finding C1 'Frontmatter' 'warning' "Skill `"$($d.Name)`" missing frontmatter key '$key'" "Add `"$key`": `"...`" between the leading --- separators in $skillFile." $skillFile 1
+        }
+    }
+    if ($fm['name'] -and ($fm['name'].ToLower() -ne $d.Name.ToLower())) {
+        Add-Finding C2 'Frontmatter' 'warning' "Directory `"$($d.Name)/`" declares name `"$($fm['name'])`"" "Rename one of them so they match." $skillFile 1
+    }
+}
+
+# === C3: every skill referenced in agent ===
+if (Test-Path $agentFile) {
+    $agentText = $mdText[$agentFile]
+    foreach ($name in $skillNames) {
+        $patternBacktick = "``$name``"
+        if ($agentText -notmatch [regex]::Escape($name)) {
+            Add-Finding C3 'Agent inventory' 'warning' "Skill `"$name`" not mentioned in kushi.agent.md" "Add a row to the routing table: ``| <verb> | $name | <one-line description> |``" $agentFile 0
+        }
+    }
+} else {
+    Add-Finding C3 'Agent inventory' 'error' "Agent file missing: $agentFile" "Create plugin/agents/kushi.agent.md as the orchestrator." $agentFile 0
+}
+
+# === C4: prompts route to real skills ===
+foreach ($p in $promptFiles) {
+    $text = $mdText[$p.FullName]
+    # Find phrases like "delegates to `name`" or "Delegates to `name` skill"
+    $matches2 = [regex]::Matches($text, "(?i)delegates? to ``([a-z0-9-]+)``")
+    foreach ($m in $matches2) {
+        $referenced = $m.Groups[1].Value
+        if ($skillNames -notcontains $referenced) {
+            Add-Finding C4 'Prompts' 'warning' "Prompt $($p.Name) references skill `"$referenced`" which doesn't exist" "Either create plugin/skills/$referenced/ or update the prompt to point at an existing skill." $p.FullName 0
+        }
+    }
+}
+
+# === C5: instructions referenced somewhere ===
+foreach ($inst in $instructionFiles) {
+    $needle = $inst.Name  # e.g. workiq-first.instructions.md
+    $referenced = $false
+    foreach ($key in $mdText.Keys) {
+        if ($key -eq $inst.FullName) { continue }
+        if ($mdText[$key] -match [regex]::Escape($needle)) { $referenced = $true; break }
+    }
+    if (-not $referenced) {
+        Add-Finding C5 'Instructions' 'warning' "Instruction `"$needle`" is orphan (not referenced from any SKILL.md or agent.md)" "Either reference it in a relevant skill (e.g. add a `## References` bullet) or delete it." $inst.FullName 0
+    }
+}
+
+# === C6: cross-links resolve ===
+foreach ($f in $allMd) {
+    $text = $mdText[$f.FullName]
+    # Strip fenced code blocks first (```...```), then inline code spans (`...`).
+    # This keeps regex examples from being treated as real links.
+    $stripped = [regex]::Replace($text, '(?s)```.*?```', { param($m) ("`n" * ($m.Value -split "`n").Count) })
+    $stripped = [regex]::Replace($stripped, '`[^`\n]+`', '')
+    $linkRx = [regex]'\]\(([^)]+)\)'
+    $i = 0
+    foreach ($line in ($stripped -split "`n")) {
+        $i++
+        foreach ($m in $linkRx.Matches($line)) {
+            $tgt = $m.Groups[1].Value.Trim()
+            # Skip absolute URLs, anchors, mailto, angle-bracket placeholders, and template variables.
+            if ($tgt -match '^(https?:|mailto:|#|<)' -or $tgt -match '^[a-zA-Z]+:') { continue }
+            if ($tgt -match '^\{\{.+\}\}$') { continue }   # {{URL}} template placeholders
+            if ($tgt -match '\.\.\.') { continue }          # path/... example syntax
+            # Strip query / fragment.
+            $tgt = ($tgt -split '[#?]')[0].Trim()
+            if (-not $tgt) { continue }
+            $resolved = Join-Path (Split-Path $f.FullName) $tgt
+            try { $resolved = [System.IO.Path]::GetFullPath($resolved) } catch { continue }
+            if (-not (Test-Path $resolved)) {
+                Add-Finding C6 'Cross-links' 'warning' "$($f.Name):$i links to `"$tgt`" which doesn't resolve" "Update or remove the link." $f.FullName $i
+            }
+        }
+    }
+}
+
+# === C7: verbs table matches prompts ===
+if (Test-Path $readmeFile) {
+    $readme = Get-Content -Raw $readmeFile
+    foreach ($p in $promptFiles) {
+        $verb = $p.BaseName -replace '\.prompt$',''
+        if ($readme -notmatch "``$verb``") {
+            Add-Finding C7 'Verbs (README)' 'warning' "Verb `"$verb`" has a prompt file but no row in README" "Add to the verbs table in README.md: ``| ``$verb`` | <window> | <description> |``" $readmeFile 0
+        }
+    }
+} else {
+    Add-Finding C7 'Verbs (README)' 'warning' "README.md not found at $readmeFile" "Create README.md and document the verbs surface." $readmeFile 0
+}
+
+# === C8: docs/reference/where-things-live.md references all top-level plugin items ===
+if (Test-Path $wtlFile) {
+    $wtl = Get-Content -Raw $wtlFile
+    foreach ($child in (Get-ChildItem $pluginDir)) {
+        if ($wtl -notmatch [regex]::Escape($child.Name)) {
+            Add-Finding C8 'Layout (WTL)' 'warning' "plugin/$($child.Name) is missing from docs/reference/where-things-live.md tree" "Add it under '## 1. This repo'." $wtlFile 0
+        }
+    }
+}
+
+# === C9: plugin.json profiles block is well-formed and references real assets ===
+$pluginJsonFile = Join-Path $pluginDir 'plugin.json'
+if (Test-Path $pluginJsonFile) {
+    try {
+        $pj = Get-Content -Raw $pluginJsonFile | ConvertFrom-Json
+        if (-not $pj.profiles) {
+            Add-Finding C9 'Profiles' 'error' 'plugin.json has no profiles block' "Add a 'profiles' block with at least core/standard/full." $pluginJsonFile 0
+        } else {
+            $profileNames = @($pj.profiles.PSObject.Properties.Name)
+            $defaultProfile = $pj.default_profile
+            if (-not $defaultProfile) {
+                Add-Finding C9 'Profiles' 'warning' "plugin.json missing 'default_profile'" "Set 'default_profile' to one of: $($profileNames -join ', ')." $pluginJsonFile 0
+            } elseif ($profileNames -notcontains $defaultProfile) {
+                Add-Finding C9 'Profiles' 'error' "default_profile '$defaultProfile' is not declared in profiles{}" "Use one of: $($profileNames -join ', ')." $pluginJsonFile 0
+            }
+            # Resolve each profile chain and verify every referenced skill/prompt/instruction exists
+            function Resolve-ProfileChain($name, $seen) {
+                if ($seen -contains $name) { return @() }
+                $p = $pj.profiles.$name
+                if (-not $p) { return @() }
+                $chain = @()
+                if ($p.extends) { $chain += Resolve-ProfileChain $p.extends ($seen + $name) }
+                $chain += $name
+                return $chain
+            }
+            $skillNames = (Get-ChildItem $skillsDir -Directory).Name
+            $promptStems = (Get-ChildItem (Join-Path $pluginDir 'prompts') -File -Filter '*.prompt.md' -ErrorAction SilentlyContinue) `
+                | ForEach-Object { $_.Name -replace '\.prompt\.md$','' }
+            $instructionStems = (Get-ChildItem (Join-Path $pluginDir 'instructions') -File -Filter '*.instructions.md' -ErrorAction SilentlyContinue) `
+                | ForEach-Object { $_.Name -replace '\.instructions\.md$','' }
+            foreach ($pn in $profileNames) {
+                $chain = Resolve-ProfileChain $pn @()
+                $skills = New-Object System.Collections.Generic.HashSet[string]
+                $prompts = New-Object System.Collections.Generic.HashSet[string]
+                $instr = $null
+                foreach ($link in $chain) {
+                    $node = $pj.profiles.$link
+                    if ($node.skills) { foreach ($s in $node.skills) { $null = $skills.Add($s) } }
+                    if ($node.prompts) { foreach ($s in $node.prompts) { $null = $prompts.Add($s) } }
+                    if ($node.instructions) { $instr = $node.instructions }
+                }
+                foreach ($s in $skills) {
+                    if ($skillNames -notcontains $s) {
+                        Add-Finding C9 'Profiles' 'warning' "Profile '$pn' references skill '$s' which doesn't exist under plugin/skills/" "Create plugin/skills/$s/ or remove it from the profile." $pluginJsonFile 0
+                    }
+                }
+                foreach ($s in $prompts) {
+                    if ($promptStems -notcontains $s) {
+                        Add-Finding C9 'Profiles' 'warning' "Profile '$pn' references prompt '$s.prompt.md' which doesn't exist" "Create plugin/prompts/$s.prompt.md or remove it from the profile." $pluginJsonFile 0
+                    }
+                }
+                if ($instr -and $instr -ne '*') {
+                    foreach ($s in $instr) {
+                        if ($instructionStems -notcontains $s) {
+                            Add-Finding C9 'Profiles' 'warning' "Profile '$pn' references instruction '$s.instructions.md' which doesn't exist" "Create plugin/instructions/$s.instructions.md or remove it from the profile." $pluginJsonFile 0
+                        }
+                    }
+                }
+            }
+        }
+
+        # === C10: reference packs referenced by any profile must exist and have a README.md ===
+        $refPacksDir = Join-Path $pluginDir 'reference-packs'
+        $profileNames = @($pj.profiles.PSObject.Properties.Name)
+        foreach ($pn in $profileNames) {
+            $packs = $pj.profiles.$pn.reference_packs
+            if ($null -eq $packs) { continue }
+            foreach ($pack in $packs) {
+                $packDir = Join-Path $refPacksDir $pack
+                if (-not (Test-Path $packDir)) {
+                    Add-Finding C10 'Reference packs' 'warning' "Profile '$pn' references reference pack '$pack' which doesn't exist" "Create plugin/reference-packs/$pack/ with a README.md, or remove the pack from the profile." $pluginJsonFile 0
+                    continue
+                }
+                $readme = Join-Path $packDir 'README.md'
+                if (-not (Test-Path $readme)) {
+                    Add-Finding C10 'Reference packs' 'warning' "Reference pack '$pack' is missing a README.md" "Create plugin/reference-packs/$pack/README.md documenting pack scope, consumers, read order, and conflict-resolution." $packDir 0
+                }
+            }
+        }
+
+        # Also: every folder UNDER reference-packs/ should have a README.md, even if not yet wired into a profile.
+        if (Test-Path $refPacksDir) {
+            $packDirs = Get-ChildItem -Path $refPacksDir -Directory -ErrorAction SilentlyContinue
+            foreach ($pd in $packDirs) {
+                $readme = Join-Path $pd.FullName 'README.md'
+                if (-not (Test-Path $readme)) {
+                    Add-Finding C10 'Reference packs' 'warning' "Reference pack folder '$($pd.Name)' has no README.md" "Create plugin/reference-packs/$($pd.Name)/README.md documenting pack scope, consumers, read order, and conflict-resolution." $pd.FullName 0
+                }
+            }
+        }
+    } catch {
+        Add-Finding C9 'Profiles' 'error' "Failed to parse plugin.json: $_" "Validate JSON syntax." $pluginJsonFile 0
+    }
+} else {
+    Add-Finding C9 'Profiles' 'error' "plugin.json not found at $pluginJsonFile" "Create plugin/plugin.json with a 'profiles' block." $pluginJsonFile 0
+}
+
+# === C11: FDE skills must cite at least one reference-pack file in SKILL.md ===
+$fdeSkills = @('fde-intake','fde-report','fde-triage')
+foreach ($name in $fdeSkills) {
+    $f = Join-Path $skillsDir "$name\SKILL.md"
+    if (Test-Path $f) {
+        $text = Get-Content -Raw $f
+        if ($text -notmatch 'reference-packs/fde/[a-zA-Z0-9_.-]+\.md') {
+            Add-Finding C11 'FDE skills' 'warning' "Skill $name doesn't cite any reference-packs/fde/*.md file" "FDE skills must ground in the FDE reference pack — cite report-doctrine.md / intake-questions.md / core-fde-reference.md as appropriate." $f 0
+        }
+    }
+}
+
+# === C12: pull-* skills must reference thoroughness-detector + evidence templates carry Validation block ===
+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
+    }
+}
+$evidenceTemplateDirs = @('templates\weekly','templates\snapshot')
+$nonEvidenceTemplates = @('consolidated.template.md','run-log.template.md')
+foreach ($td in $evidenceTemplateDirs) {
+    $dir = Join-Path $pluginDir $td
+    if (-not (Test-Path $dir)) { continue }
+    Get-ChildItem $dir -Filter '*.template.md' -ErrorAction SilentlyContinue | ForEach-Object {
+        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
+        }
+    }
+}
+$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
+}
+$detectorFile = Join-Path $pluginDir 'instructions\thoroughness-detector.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
+}
+
+# === Deep checks ===
+if ($Deep) {
+    # D1: templates referenced from skills exist
+    $templatesDir = Join-Path $pluginDir 'templates'
+    foreach ($d in $skillDirs) {
+        $f = Join-Path $d.FullName 'SKILL.md'
+        $text = $mdText[$f]
+        if (-not $text) { continue }
+        foreach ($m in [regex]::Matches($text, '``templates/([a-zA-Z0-9_./-]+\.template\.[a-z]+)``')) {
+            $rel = $m.Groups[1].Value
+            $abs = Join-Path $templatesDir $rel
+            if (-not (Test-Path $abs)) {
+                Add-Finding D1 'Templates' 'warning' "Skill $($d.Name) references templates/$rel which doesn't exist" "Create the template or update the path." $f 0
+            }
+        }
+    }
+    # D2: pull-* skills must reference snapshot-vs-stream
+    foreach ($d in $skillDirs | Where-Object { $_.Name -like 'pull-*' }) {
+        $f = Join-Path $d.FullName 'SKILL.md'
+        $text = $mdText[$f]
+        if ($text -notmatch 'snapshot-vs-stream\.instructions\.md') {
+            Add-Finding D2 'Snapshot/Stream' 'warning' "Skill $($d.Name) doesn't cite snapshot-vs-stream.instructions.md" "Add a reference (e.g. 'per snapshot-vs-stream.instructions.md') in the skill body." $f 0
+        }
+    }
+    # D3: pull-* must put WorkIQ first
+    foreach ($d in $skillDirs | Where-Object { $_.Name -like 'pull-*' }) {
+        $f = Join-Path $d.FullName 'SKILL.md'
+        $text = $mdText[$f]
+        if ($text -notmatch '(?ms)1\.\s*\*\*WorkIQ\*\*') {
+            Add-Finding D3 'WorkIQ-first' 'warning' "Skill $($d.Name) doesn't list **WorkIQ** as tool #1" "Restructure the Tools section so WorkIQ is item 1." $f 0
+        }
+    }
+    # D4: live install SKILL.md = agent file
+    $liveSkill = Join-Path $env:USERPROFILE '.copilot\m-skills\kushi\SKILL.md'
+    if (Test-Path $liveSkill) {
+        $a = Get-FileHash $liveSkill -Algorithm SHA256
+        $b = Get-FileHash $agentFile -Algorithm SHA256
+        if ($a.Hash -ne $b.Hash) {
+            Add-Finding D4 'Live install sync' 'warning' "Live SKILL.md hash differs from plugin/agents/kushi.agent.md" "Re-run installer: ``node bin/cli.mjs --clawpilot --force``" $liveSkill 0
+        }
+    }
+    # D5: skills-metadata description matches frontmatter
+    $metaPath = Join-Path $env:USERPROFILE '.copilot\m-skills\skills-metadata.json'
+    if (Test-Path $metaPath) {
+        try {
+            $meta = Get-Content -Raw $metaPath | ConvertFrom-Json
+            $kushiMeta = $meta | Where-Object { $_.name -eq 'kushi' } | Select-Object -First 1
+            if ($kushiMeta) {
+                $fmAgent = Get-Frontmatter $agentFile
+                if ($fmAgent['description'] -and $kushiMeta.description -ne $fmAgent['description']) {
+                    Add-Finding D5 'Live install sync' 'warning' "skills-metadata.json kushi description drifted from agent frontmatter" "Re-run installer or sync the description manually." $metaPath 0
+                }
+            }
+        } catch {
+            Add-Finding D5 'Live install sync' 'warning' "Failed to parse skills-metadata.json: $_" "Validate JSON syntax." $metaPath 0
+        }
+    }
+    # D6: side-by-side rule cited where user config is touched
+    $configTouchers = @('bootstrap-project','refresh-project')  # heuristic
+    foreach ($name in $configTouchers) {
+        $f = Join-Path $skillsDir "$name\SKILL.md"
+        if (Test-Path $f) {
+            $text = $mdText[$f]
+            if ($text -notmatch 'side-by-side-config\.instructions\.md') {
+                Add-Finding D6 'Instructions' 'warning' "Skill $name doesn't cite side-by-side-config.instructions.md" "Add a reference; this skill writes user-visible config files." $f 0
+            }
+        }
+    }
+    # D7: live install kushi-install.json matches plugin.json profile spec
+    $liveManifest = Join-Path $env:USERPROFILE '.copilot\m-skills\kushi\kushi-install.json'
+    if (Test-Path $liveManifest) {
+        try {
+            $live = Get-Content -Raw $liveManifest | ConvertFrom-Json
+            $pluginJsonFile2 = Join-Path $pluginDir 'plugin.json'
+            $pj2 = Get-Content -Raw $pluginJsonFile2 | ConvertFrom-Json
+            $liveProfile = $live.profile
+            if ($pj2.profiles.$liveProfile) {
+                # Re-resolve chain
+                function Resolve-ChainD7($name, $seen) {
+                    if ($seen -contains $name) { return @() }
+                    $p = $pj2.profiles.$name
+                    if (-not $p) { return @() }
+                    $chain = @()
+                    if ($p.extends) { $chain += Resolve-ChainD7 $p.extends ($seen + $name) }
+                    $chain += $name
+                    return $chain
+                }
+                $chain = Resolve-ChainD7 $liveProfile @()
+                $expectedSkills = New-Object System.Collections.Generic.HashSet[string]
+                foreach ($link in $chain) {
+                    $node = $pj2.profiles.$link
+                    if ($node.skills) { foreach ($s in $node.skills) { $null = $expectedSkills.Add($s) } }
+                }
+                $missing = @($expectedSkills | Where-Object { $live.skills -notcontains $_ })
+                $extra = @($live.skills | Where-Object { -not $expectedSkills.Contains($_) })
+                if ($missing.Count -gt 0 -or $extra.Count -gt 0) {
+                    Add-Finding D7 'Live install manifest' 'warning' "Live kushi-install.json (profile '$liveProfile') drifted from plugin.json — missing: [$($missing -join ', ')]; extra: [$($extra -join ', ')]" "Re-run installer: ``node bin/cli.mjs --clawpilot --profile $liveProfile --force``" $liveManifest 0
+                }
+
+                # Reference packs drift check
+                $expectedPacks = New-Object System.Collections.Generic.HashSet[string]
+                foreach ($link in $chain) {
+                    $node = $pj2.profiles.$link
+                    if ($node.reference_packs) { foreach ($s in $node.reference_packs) { $null = $expectedPacks.Add($s) } }
+                }
+                $livePacks = @()
+                if ($live.PSObject.Properties.Name -contains 'reference_packs') { $livePacks = @($live.reference_packs) }
+                $packMissing = @($expectedPacks | Where-Object { $livePacks -notcontains $_ })
+                $packExtra = @($livePacks | Where-Object { -not $expectedPacks.Contains($_) })
+                if ($packMissing.Count -gt 0 -or $packExtra.Count -gt 0) {
+                    Add-Finding D7 'Live install manifest' 'warning' "Live kushi-install.json reference_packs (profile '$liveProfile') drifted from plugin.json — missing: [$($packMissing -join ', ')]; extra: [$($packExtra -join ', ')]" "Re-run installer: ``node bin/cli.mjs --clawpilot --profile $liveProfile --force``" $liveManifest 0
+                }
+            } else {
+                Add-Finding D7 'Live install manifest' 'warning' "Live install profile '$liveProfile' not declared in plugin.json" "Re-install with a known profile (core/standard/full)." $liveManifest 0
+            }
+        } catch {
+            Add-Finding D7 'Live install manifest' 'warning' "Failed to parse live kushi-install.json: $_" "Re-run installer to rewrite the manifest." $liveManifest 0
+        }
+    }
+
+    # D8: live templates/fde/ matches repo
+    $liveFdeTpl = Join-Path $env:USERPROFILE '.copilot\m-skills\kushi\templates\fde'
+    $repoFdeTpl = Join-Path $pluginDir 'templates\fde'
+    if ((Test-Path $liveFdeTpl) -and (Test-Path $repoFdeTpl)) {
+        $liveFiles = Get-ChildItem -Path $liveFdeTpl -File -Filter '*.md' -ErrorAction SilentlyContinue
+        $repoFiles = Get-ChildItem -Path $repoFdeTpl -File -Filter '*.md' -ErrorAction SilentlyContinue
+        $liveNames = @($liveFiles | ForEach-Object { $_.Name })
+        $repoNames = @($repoFiles | ForEach-Object { $_.Name })
+        $missing = @($repoNames | Where-Object { $liveNames -notcontains $_ })
+        $extra = @($liveNames | Where-Object { $repoNames -notcontains $_ })
+        if ($missing.Count -gt 0 -or $extra.Count -gt 0) {
+            Add-Finding D8 'Live templates' 'warning' "Live templates/fde/ drifted from repo — missing: [$($missing -join ', ')]; extra: [$($extra -join ', ')]" "Re-run installer to sync FDE templates." $liveFdeTpl 0
+        } else {
+            foreach ($rf in $repoFiles) {
+                $lf = Join-Path $liveFdeTpl $rf.Name
+                $rh = (Get-FileHash $rf.FullName -Algorithm SHA256).Hash
+                $lh = (Get-FileHash $lf -Algorithm SHA256).Hash
+                if ($rh -ne $lh) {
+                    Add-Finding D8 'Live templates' 'warning' "FDE template $($rf.Name) hash differs between repo and live install" "Re-run installer to sync." $lf 0
+                }
+            }
+        }
+    }
+}
+
+# === Output ===
+if ($Json) {
+    $findings | ConvertTo-Json -Depth 6
+} else {
+    $version = (Get-Frontmatter $agentFile).version
+    if (-not $version) {
+        try { $version = (Get-Content -Raw (Join-Path $Root 'package.json') | ConvertFrom-Json).version } catch {}
+    }
+    $stamp = Get-Date -Format 'yyyy-MM-dd HH:mm'
+    Write-Host ""
+    Write-Host "### Self-Check Results — Kushi v$version @ $stamp"
+    Write-Host ""
+
+    $bySurface = $findings | Group-Object surface
+    if ($findings.Count -eq 0) {
+        Write-Host "✅ All checks passed. Safe to commit."
+    } else {
+        $coreCount = ($findings | Where-Object { $_.code -notlike 'D*' }).Count
+        $deepCount = ($findings | Where-Object { $_.code -like 'D*' }).Count
+        Write-Host "| Surface | Count |"
+        Write-Host "|---------|------:|"
+        foreach ($g in $bySurface | Sort-Object Name) {
+            Write-Host ("| {0} | {1} |" -f $g.Name, $g.Count)
+        }
+        Write-Host ""
+        Write-Host "Findings:"
+        Write-Host ""
+        foreach ($x in $findings) {
+            $loc = if ($x.line) { ":$($x.line)" } else { "" }
+            Write-Host "⚠️  [$($x.code)] $($x.message)"
+            Write-Host "    file: $($x.file)$loc"
+            Write-Host "    fix : $($x.fix)"
+            Write-Host ""
+        }
+        Write-Host "⚠️ Found $($findings.Count) gap(s) — $coreCount core, $deepCount deep. Review and update before committing."
+    }
+}
+
+if ($StrictExit -and $findings.Count -gt 0) { exit 1 }
+exit 0

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

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Cross-OS wrapper for run.ps1.
+# pwsh 7+ runs the same script unchanged on macOS / Linux / WSL / Windows.
+#
+# Why a wrapper instead of a native bash port?
+#   The check logic relies on regex over markdown + YAML frontmatter parsing
+#   + SHA256 hashing. PowerShell 7 has all of this in stdlib and is officially
+#   supported on macOS and Linux. A bash port would double the maintenance
+#   burden and drift over time. self-check D-checks already verify the .ps1
+#   stays consistent with the doctrine in SKILL.md.
+#
+# Install pwsh on macOS:  brew install --cask powershell
+# Install pwsh on Ubuntu: https://learn.microsoft.com/powershell/scripting/install/install-ubuntu
+#
+# Usage (matches run.ps1 exactly):
+#   ./run.sh                       # core checks, human output
+#   ./run.sh -Deep                 # core + deep checks
+#   ./run.sh -Json                 # JSON output (empty array = no findings)
+#   ./run.sh -Deep -StrictExit     # CI-friendly: exit 1 on any finding
+#   ./run.sh -Root /path/to/kushi  # check a specific kushi root
+
+set -euo pipefail
+
+if ! command -v pwsh >/dev/null 2>&1; then
+  echo "Error: pwsh (PowerShell 7+) is required." >&2
+  echo "  macOS:  brew install --cask powershell" >&2
+  echo "  Ubuntu: see https://learn.microsoft.com/powershell/scripting/install/install-ubuntu" >&2
+  echo "  Other:  https://github.com/PowerShell/PowerShell/releases" >&2
+  exit 127
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec pwsh -NoProfile -File "${SCRIPT_DIR}/run.ps1" "$@"

package/plugin/templates/fde/intake.md

@@ -0,0 +1,114 @@
+# FDE Intake — {{customer_name}} · {{engagement_title}} ({{division_or_team}})
+
+**MSX Opportunity:** `{{msx_opportunity_id}}`
+
+> **Document type:** FDE Intake (first artifact in this engagement)
+> **Last updated:** {{generated_at}}
+> **Generated by:** Kushi `fde-intake` v{{kushi_version}}
+
+{{freshness_warning_block}}
+
+---
+
+## Q1 — Who you are currently engaged with or have engaged with
+
+{{q1_stakeholders}}
+
+> Required: ATU representation, Industry Team representation.
+> Optional but explicitly stated: ISE, ISD, Executive Sponsor, Product Group.
+
+---
+
+## Q2 — Business scenario or technical blocker FDE would solve
+
+{{q2_scenario}}
+
+**Quantified business impact:** {{q2_impact_dollars}}
+
+**Outcome chain (technical intervention → KPI → business outcome):**
+
+- {{q2_chain_1}}
+- {{q2_chain_2}}
+- {{q2_chain_3}}
+
+---
+
+## Q3 — Why current offers / solutions are not suitable
+
+{{q3_gaps}}
+
+---
+
+## Q4 — What does success look like for the customer
+
+### Outcome hypothesis
+
+> *"If we {{q4_intervention}}, then {{q4_kpi}} will improve by {{q4_target}} within {{q4_timeframe}}, as measured by {{q4_method}} against {{q4_baseline}}."*
+
+### Quantified success criteria (≥ 2 KPIs)
+
+| KPI | Baseline | Target | Timeframe | Measurement method |
+|---|---|---|---|---|
+| {{kpi1_name}} | {{kpi1_baseline}} | {{kpi1_target}} | {{kpi1_timeframe}} | {{kpi1_method}} |
+| {{kpi2_name}} | {{kpi2_baseline}} | {{kpi2_target}} | {{kpi2_timeframe}} | {{kpi2_method}} |
+
+### Baseline
+
+{{q4_baseline_detail}}
+
+### ROI framing
+
+> {{q4_roi_statement}}
+
+### Value realization plan
+
+{{q4_value_realization}}
+
+### Catcher team
+
+{{q4_catcher_team}}
+
+---
+
+## Q5 — Relevant technology workloads
+
+{{q5_technologies}}
+
+---
+
+## Q6 — Work completed so far
+
+{{q6_completed_work}}
+
+### Commercial posture
+
+| Item | Value | Source |
+|---|---|---|
+| Current yearly ACR | {{q6_acr_current}} | {{q6_acr_source}} |
+| ACR growth trajectory | {{q6_acr_growth}} | {{q6_acr_growth_source}} |
+| Expected program ACR (if successful) | {{q6_acr_expected}} | {{q6_acr_expected_source}} |
+| MACC in place | {{q6_macc_in_place}} | {{q6_macc_source}} |
+| MACC pending | {{q6_macc_pending}} | {{q6_macc_pending_source}} |
+| Customer ROI (their own) | {{q6_customer_roi}} | {{q6_customer_roi_source}} |
+
+### Customer readiness
+
+{{q6_customer_readiness}}
+
+---
+
+## Validation warnings (open)
+
+{{validation_warnings_block}}
+
+---
+
+## Source coverage
+
+| Source | Status |
+|---|---|
+{{source_coverage_rows}}
+
+---
+
+> _This document was generated by Kushi (`fde-intake`) from `<project>/Evidence/` and the FDE reference pack. Every assertion carries an inline `[source: …]` citation. Edit in place as the engagement evolves — Kushi will preserve manual edits on re-run when the `--merge` flag is supplied._