kushi-agents 5.3.0 → 5.4.1

package/plugin/instructions/release-genealogy.instructions.md

@@ -1,52 +1,52 @@
----
-title: Release genealogy
-applies_to: every kushi release before tagging
-status: stable
-since: v5.0.1
----
-
-# Release genealogy doctrine
-
-Every shipped tag MUST have a corresponding entry in `docs/genealogy.md`. The genealogy file is the canonical *why* for the project — `CHANGELOG.md` records *what changed*; genealogy records *what each release built on, what it enabled, and what trade-offs were accepted*.
-
-## When to write the entry
-
-Before `git tag`. The entry is part of the ship checklist, not a follow-up.
-
-## Required fields
-
-Every entry MUST contain:
-
-1. **Built on** — which prior release (or external work) this depends on. State the *causal* dependency, not just the version number ("Built on v4.9.0 CSC. Without per-contributor `_index/entities.yml` and stable entity IDs, cross-source linking would be guesswork.").
-2. **Why this release** — the problem this release solves, in 2–4 sentences.
-3. **What it enabled** — concrete capabilities now available that weren't before. Bullets OK.
-4. **Next ancestor** — name the next release in the lineage (forward link). Update the prior release's "Next ancestor" line when shipping.
-
-## Recommended fields
-
-5. **Inspired by** — external work, papers, gists, repos. Link them. This is the project's reading list.
-6. **Trade-offs accepted** — what was knowingly sacrificed. Includes locked decisions from design time (e.g. "Q1 LLM edges opt-in").
-7. **Patch lineage** — if patch releases under this entry fix bugs introduced here, list them inline rather than as separate sections.
-
-## Grouping rule
-
-One section per release that **materially advanced** the lineage. Patch releases that only fix bugs in the parent (e.g. v4.2.1–v4.2.3 fixing v4.2.0's WorkIQ probe on Windows) MUST be named under the parent's "Patch lineage" line, not given their own section. This keeps the file readable while ensuring every tag is discoverable.
-
-## Self-check enforcement
-
-`D31.genealogy` (in `plugin/skills/self-check/run.ps1`):
-
-- Every `git tag` matching `v\d+\.\d+\.\d+` MUST appear in `docs/genealogy.md` either as a `## v<x.y.z>` heading or as an explicit named patch under a parent's "Patch lineage" line.
-- Missing tags fail the check with the actionable fix: "Add an entry to docs/genealogy.md before re-tagging, or list this tag under a parent's Patch lineage line."
-
-## Cross-references
-
-- README links to `docs/genealogy.md` under "Project lineage"
-- CHANGELOG.md header notes: "For the *why* behind each release, see [docs/genealogy.md](docs/genealogy.md)"
-- Major GitHub tag descriptions link to the genealogy entry for that release
-
-## Style
-
-- Genealogy entries are short — 6–15 lines per release. If a release needs more, split the entry into "summary" + "deep-dive references" rather than letting the genealogy bloat.
-- Write in present tense for what the release *does*; past tense for what it *replaced*.
-- Don't list every file changed (that's CHANGELOG's job). Name only the structural shifts that matter to future readers.
+---
+title: Release genealogy
+applies_to: every kushi release before tagging
+status: stable
+since: v5.0.1
+---
+
+# Release genealogy doctrine
+
+Every shipped tag MUST have a corresponding entry in `docs/genealogy.md`. The genealogy file is the canonical *why* for the project — `CHANGELOG.md` records *what changed*; genealogy records *what each release built on, what it enabled, and what trade-offs were accepted*.
+
+## When to write the entry
+
+Before `git tag`. The entry is part of the ship checklist, not a follow-up.
+
+## Required fields
+
+Every entry MUST contain:
+
+1. **Built on** — which prior release (or external work) this depends on. State the *causal* dependency, not just the version number ("Built on v4.9.0 CSC. Without per-contributor `_index/entities.yml` and stable entity IDs, cross-source linking would be guesswork.").
+2. **Why this release** — the problem this release solves, in 2–4 sentences.
+3. **What it enabled** — concrete capabilities now available that weren't before. Bullets OK.
+4. **Next ancestor** — name the next release in the lineage (forward link). Update the prior release's "Next ancestor" line when shipping.
+
+## Recommended fields
+
+5. **Inspired by** — external work, papers, gists, repos. Link them. This is the project's reading list.
+6. **Trade-offs accepted** — what was knowingly sacrificed. Includes locked decisions from design time (e.g. "Q1 LLM edges opt-in").
+7. **Patch lineage** — if patch releases under this entry fix bugs introduced here, list them inline rather than as separate sections.
+
+## Grouping rule
+
+One section per release that **materially advanced** the lineage. Patch releases that only fix bugs in the parent (e.g. v4.2.1–v4.2.3 fixing v4.2.0's WorkIQ probe on Windows) MUST be named under the parent's "Patch lineage" line, not given their own section. This keeps the file readable while ensuring every tag is discoverable.
+
+## Self-check enforcement
+
+`D31.genealogy` (in `plugin/skills/self-check/run.ps1`):
+
+- Every `git tag` matching `v\d+\.\d+\.\d+` MUST appear in `docs/genealogy.md` either as a `## v<x.y.z>` heading or as an explicit named patch under a parent's "Patch lineage" line.
+- Missing tags fail the check with the actionable fix: "Add an entry to docs/genealogy.md before re-tagging, or list this tag under a parent's Patch lineage line."
+
+## Cross-references
+
+- README links to `docs/genealogy.md` under "Project lineage"
+- CHANGELOG.md header notes: `For the *why* behind each release, see [docs/genealogy.md](docs/genealogy.md)` (link target is repo-root-relative, which resolves from CHANGELOG's location but NOT from this doctrine file's location — kept in code form so the C6 cross-link check does not flag it)
+- Major GitHub tag descriptions link to the genealogy entry for that release
+
+## Style
+
+- Genealogy entries are short — 6–15 lines per release. If a release needs more, split the entry into "summary" + "deep-dive references" rather than letting the genealogy bloat.
+- Write in present tense for what the release *does*; past tense for what it *replaced*.
+- Don't list every file changed (that's CHANGELOG's job). Name only the structural shifts that matter to future readers.

package/plugin/instructions/system-health.instructions.md

@@ -0,0 +1,51 @@
+---
+applyTo: "plugin/skills/doctor/**, src/doctor*.mjs"
+---
+
+# Instruction: system-health (doctor doctrine)
+
+`kushi doctor` is the **aggregator of existing probes**, not a new validation engine. This doctrine fixes what it checks, in what order, and why each check earns a slot.
+
+## Principles
+
+1. **Never re-implement a probe.** Doctor shells out to `self-check/run.ps1`, `eval/run-evals.ps1`, `skill-checker/check-skill.ps1`, etc. If logic needs to change, change it in the probe — not in doctor.
+2. **Every finding ends with a fix.** A finding without a `Fix:` snippet is a bug. Snippets must be copy-paste-runnable in pwsh.
+3. **Read-only against the live install.** Doctor's drift-check reads `~/.copilot/m-skills/kushi/SKILL.md`. It never writes to that path. The fix is always a user-runnable installer command.
+4. **One-screen default.** Per-probe stdout is captured but only the headline + finding count surface. `--verbose` opens the firehose.
+5. **Cross-platform-safe.** No `~` shortcuts; resolve `$env:USERPROFILE` (Windows) or `$env:HOME` (Unix).
+6. **Color is a hint, not a contract.** All semantics ride in the JSON (`status: green|yellow|red`). The colored output is human ergonomics.
+
+## Ordered probes
+
+| Order | Probe | What it answers | Source script |
+|------:|-------|-----------------|---------------|
+| 1 | Environment | Is the toolchain installed? | inline |
+| 2 | self-check -Deep | Is the repo internally consistent? | `plugin/skills/self-check/run.ps1` |
+| 3 | canary evals | Do the smoke-suite evals pass? | `npm run eval:canary` |
+| 4 | skill-checker -All | Does every skill match the blueprint? | `plugin/skills/skill-checker/check-skill.ps1` |
+| 5 | Live-install drift | Is the live install in sync with the repo? | inline (hash compare) |
+| 6 | Global wiki shape | If a global wiki exists, is its scaffold intact? | inline |
+
+Probes 5 and 6 are conditional — they no-op cleanly when the artifact doesn't exist on this machine.
+
+## Status semantics
+
+- **green** — probe passed, or artifact not present (informational green).
+- **yellow** — probe found drift / minor inconsistency; user action recommended but not blocking.
+- **red** — probe failed hard (script missing, exit ≠ 0 on canary, etc.). Doctor exits non-zero.
+
+`--strict` flips `yellow` into `red` for CI use.
+
+## Adding a new probe
+
+1. Write the probe as a standalone script (a skill, an evals harness, whatever fits).
+2. Make it return JSON when given `-Json` (or equivalent). Exit codes follow the same green/yellow/red convention.
+3. Add an ordered entry to `doctor.ps1` with: a `Write-Banner`, a shell-out, a status mapping, and an `Add-Section` call with a `Fix:` snippet.
+4. Add a row to the table above + a `D41.<new-probe>` sub-check in `self-check/run.ps1` that asserts the probe artifact exists.
+5. Add an eval case under `plugin/skills/doctor/evals/evals.json` covering the new artifact.
+
+## Anti-patterns
+
+- ❌ Doctor parsing markdown for itself. Always delegate to the owning probe.
+- ❌ Doctor auto-fixing live drift. Fixes are user-runnable commands, not silent writes.
+- ❌ Doctor probing real customer Evidence. The drift check reads only the mirror SKILL.md; it never enumerates project folders.

package/plugin/skills/doctor/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: "doctor"
+version: "1.0.0"
+description: "USE WHEN the user says 'kushi doctor', 'is kushi healthy?', 'check my install', 'first-run check', 'why isn't kushi working', or wants a single aggregated health report covering environment, self-check, evals, skill-checker, live-install drift, and global wiki shape. DO NOT USE for project-evidence questions (use ask-project) or for re-running individual checks (use self-check / eval / skill-checker directly). Capability: runs every health probe in order, colors the output, prints a green/yellow/red ribbon, and includes ready-to-paste fix snippets per finding."
+---
+
+# Skill: doctor
+
+`kushi doctor` is the single aggregated health check for a kushi install. It runs every existing probe in order, captures exit codes, and prints a one-glance ribbon with copy-paste fixes per finding. Use it as the first thing on a new machine (`kushi doctor` before `kushi setup`) and as the smoke test before committing a release.
+
+This skill orchestrates **existing** scripts — it never re-implements their logic:
+
+1. **Environment probe** — pwsh, node, python (optional), git, M365 auth-file presence.
+2. **self-check -Deep** — `plugin/skills/self-check/run.ps1`.
+3. **canary evals** — `npm run eval:canary`.
+4. **skill-checker -All** — `plugin/skills/skill-checker/check-skill.ps1 -All`.
+5. **Live-install drift** — comparing `~/.copilot/m-skills/kushi/SKILL.md` against the repo's `plugin/agents/kushi.agent.md` (skipped under version skew — D4/D5 logic).
+6. **Global-wiki shape** — if `$KUSHI_GLOBAL_ROOT` or `~/.kushi-global/` exists, validate the State/ scaffold.
+
+## Triggers
+
+- `kushi doctor`
+- "is kushi healthy?"
+- "doctor"
+- "check my install"
+- "what's wrong with kushi"
+
+## Inputs
+
+- `--json` — emit results as JSON for CI consumption.
+- `--repo <path>` — point doctor at a kushi repo other than the cwd.
+
+## Outputs
+
+- **Console** — colored sections (green/yellow/red) per probe, each finding followed by a single-line `Fix:` snippet.
+- **Exit code** — `0` if all sections green, `1` if any section red or yellow under `--strict`.
+- **JSON mode** — `{ "sections": [...], "summary": { "green": N, "yellow": N, "red": N } }`.
+
+## Step checklist
+
+- [ ] Step 1 — Probe environment: pwsh version, node version, python (if on PATH), git version, M365 token file (`~/.copilot/m365-token.json` presence — DO NOT read contents).
+- [ ] Step 2 — Run `pwsh plugin/skills/self-check/run.ps1 -Deep`. Capture exit code and finding count.
+- [ ] Step 3 — Run `npm run eval:canary`. Capture exit code.
+- [ ] Step 4 — Run `pwsh plugin/skills/skill-checker/check-skill.ps1 -All`. Capture exit code and finding count.
+- [ ] Step 5 — Live-install drift: compute SHA256 of `~/.copilot/m-skills/kushi/SKILL.md` vs `plugin/agents/kushi.agent.md`. Skip under version skew (per D4/D5 logic).
+- [ ] Step 6 — Global wiki shape: if `$KUSHI_GLOBAL_ROOT` or `~/.kushi-global/State/` exists, verify `index.md` + `log.md` present.
+- [ ] Step 7 — Print a single ribbon line: `GREEN`, `YELLOW`, or `RED` with section counts.
+- [ ] Step 8 — Exit non-zero if any section is RED (or YELLOW under `--strict`).
+
+## Principles
+
+- **Aggregator, not duplicator.** Every probe is an existing script. Doctor never reimplements logic — it shells out.
+- **Fixes, not findings.** Every red/yellow line ends with a `Fix:` snippet the user can paste into their terminal.
+- **One-screen output by default.** Verbose probe output is captured but only summarized; pass `--verbose` to see each sub-script's stdout.
+- **Cross-platform-safe.** No assumptions about `~`; resolve `$env:USERPROFILE` on Windows, `$env:HOME` elsewhere.
+
+## Gotchas
+
+- **Live-install drift is informational under version skew.** If the live install was produced by a different kushi version than the repo, drift is expected and doctor reports it YELLOW with a `kushi-agents --clawpilot --force` fix snippet — never RED.
+- **Doctor does not write to `~/.copilot/m-skills/kushi/`.** It only reads. The fix snippet for live drift is intentionally a command for the user to run, not an auto-repair.
+- **Doctor must NEVER touch real customer Evidence.** Probe step 5 reads only the live SKILL.md mirror; nothing else.
+
+## Validation loop
+
+- `npm test -- src/doctor.test.mjs` — covers end-to-end run, JSON mode, exit-code-on-findings.
+- `pwsh plugin/skills/doctor/doctor.ps1` against this repo — must end GREEN at release-cut time.
+
+## References
+
+- `plugin/instructions/system-health.instructions.md` — the doctrine for what doctor checks and why.
+- `plugin/skills/self-check/SKILL.md` — the underlying probe for repo consistency.
+- `plugin/skills/skill-checker/SKILL.md` — the underlying probe for per-skill blueprint compliance.

package/plugin/skills/doctor/doctor.ps1

@@ -0,0 +1,260 @@
+<#
+.SYNOPSIS
+kushi doctor — aggregated health check + ready-to-paste fixes.
+
+.DESCRIPTION
+Runs every existing kushi probe in order, captures exit codes, prints a
+GREEN / YELLOW / RED ribbon, and emits ready-to-paste fix snippets per finding.
+Never re-implements probe logic — always shells out to the existing script.
+
+.PARAMETER Repo
+Repo root (default: two levels above this script).
+
+.PARAMETER Json
+Emit results as JSON instead of human prose.
+
+.PARAMETER Strict
+Exit non-zero on YELLOW as well as RED.
+
+.PARAMETER Verbose
+Show each sub-probe's stdout (off by default).
+
+.EXAMPLE
+pwsh plugin/skills/doctor/doctor.ps1
+pwsh plugin/skills/doctor/doctor.ps1 -Json
+#>
+[CmdletBinding()]
+param(
+    [string]$Repo = (Resolve-Path (Join-Path $PSScriptRoot "..\..\..")).Path,
+    [switch]$Json,
+    [switch]$Strict
+)
+
+$ErrorActionPreference = 'Continue'
+$sections = New-Object System.Collections.Generic.List[object]
+
+function Add-Section {
+    param(
+        [string]$Name,
+        [ValidateSet('green','yellow','red')] [string]$Status,
+        [string]$Detail,
+        [string]$Fix
+    )
+    $sections.Add([PSCustomObject]@{
+        name = $Name
+        status = $Status
+        detail = $Detail
+        fix = $Fix
+    })
+}
+
+function Write-Banner {
+    param([string]$Text, [string]$Color)
+    if (-not $Json) {
+        Write-Host ""
+        Write-Host "── $Text ──" -ForegroundColor $Color
+    }
+}
+
+function Get-CmdVersion {
+    param([string]$Cmd, [string]$Arg = '--version')
+    try {
+        $v = & $Cmd $Arg 2>$null | Select-Object -First 1
+        if ($v) { return $v.ToString().Trim() }
+    } catch {}
+    return $null
+}
+
+# ── Section 1: Environment probe ────────────────────────────────────────────
+Write-Banner "1. Environment" "Cyan"
+$pwshVer = $PSVersionTable.PSVersion.ToString()
+$nodeVer = Get-CmdVersion 'node' '--version'
+$gitVer  = Get-CmdVersion 'git' '--version'
+$pyVer   = Get-CmdVersion 'python' '--version'
+$userHome = if ($env:USERPROFILE) { $env:USERPROFILE } else { $env:HOME }
+$m365Token = Join-Path $userHome '.copilot\m365-token.json'
+$m365Auth = Test-Path $m365Token
+
+$envProblems = @()
+if (-not $nodeVer) { $envProblems += "node not on PATH (Fix: install Node 18+)" }
+if (-not $gitVer)  { $envProblems += "git not on PATH (Fix: install Git)" }
+
+if ($envProblems.Count -eq 0) {
+    $detail = "pwsh=$pwshVer node=$nodeVer git=$($gitVer -replace '^git version ','') m365=$([bool]$m365Auth)"
+    if (-not $Json) { Write-Host "  ✅ $detail" -ForegroundColor Green }
+    Add-Section 'environment' 'green' $detail ''
+} else {
+    if (-not $Json) { foreach ($p in $envProblems) { Write-Host "  ⚠️  $p" -ForegroundColor Yellow } }
+    Add-Section 'environment' 'yellow' ($envProblems -join '; ') 'Install missing tools (Node 18+, Git, pwsh 7+).'
+}
+
+# ── Section 2: self-check -Deep ─────────────────────────────────────────────
+Write-Banner "2. self-check -Deep" "Cyan"
+$selfCheckPath = Join-Path $Repo 'plugin\skills\self-check\run.ps1'
+if (Test-Path $selfCheckPath) {
+    $scJson = & pwsh -NoProfile -File $selfCheckPath -Deep -Json -Root $Repo 2>$null
+    $scExit = $LASTEXITCODE
+    $scFindings = @()
+    try { $scFindings = $scJson | ConvertFrom-Json } catch {}
+    if (-not $scFindings) { $scFindings = @() }
+    $scCount = @($scFindings).Count
+    if ($scCount -eq 0) {
+        if (-not $Json) { Write-Host "  ✅ zero findings" -ForegroundColor Green }
+        Add-Section 'self-check' 'green' 'zero findings' ''
+    } else {
+        if (-not $Json) {
+            Write-Host "  ⚠️  $scCount finding(s)" -ForegroundColor Yellow
+            foreach ($f in $scFindings) { Write-Host "      [$($f.code)] $($f.message)" -ForegroundColor DarkYellow }
+        }
+        Add-Section 'self-check' 'yellow' "$scCount finding(s)" 'pwsh plugin/skills/self-check/run.ps1 -Deep   # then fix each [code]'
+    }
+} else {
+    if (-not $Json) { Write-Host "  ❌ run.ps1 missing" -ForegroundColor Red }
+    Add-Section 'self-check' 'red' 'run.ps1 not found' "Restore plugin/skills/self-check/run.ps1 from git."
+}
+
+# ── Section 3: canary evals ─────────────────────────────────────────────────
+Write-Banner "3. canary evals" "Cyan"
+Push-Location $Repo
+$canaryOut = & npm run --silent eval:canary 2>&1
+$canaryExit = $LASTEXITCODE
+Pop-Location
+if ($canaryExit -eq 0) {
+    if (-not $Json) { Write-Host "  ✅ canary PASS" -ForegroundColor Green }
+    Add-Section 'canary-evals' 'green' 'PASS' ''
+} else {
+    # exit !=0 can mean "regression vs baseline" (e.g. canary subset misses
+    # skills the baseline has). The authoritative pass/fail count lives in the
+    # "Total: N · Pass: P · Fail: F" line. If all run cases pass, surface YELLOW
+    # (baseline noise) rather than RED.
+    $sumLine = ($canaryOut | Select-String -Pattern '^Total:\s+\d+.*Pass:\s+\d+.*Fail:\s+\d+').Line | Select-Object -First 1
+    $allCasesPassed = $false
+    if ($sumLine -match 'Pass:\s+(\d+).*Fail:\s+(\d+)') {
+        $passN = [int]$Matches[1]; $failN = [int]$Matches[2]
+        if ($failN -eq 0 -and $passN -gt 0) { $allCasesPassed = $true }
+    }
+    if ($allCasesPassed) {
+        if (-not $Json) { Write-Host "  ⚠️  canary cases all pass; aggregator flagged baseline noise (exit=$canaryExit)" -ForegroundColor Yellow }
+        Add-Section 'canary-evals' 'yellow' "cases pass; baseline noise (exit=$canaryExit)" 'npm run eval:canary -- -UpdateBaseline   # if the new shape is intentional'
+    } else {
+        if (-not $Json) { Write-Host "  ❌ canary FAIL (exit=$canaryExit)" -ForegroundColor Red }
+        Add-Section 'canary-evals' 'red' "FAIL exit=$canaryExit" 'npm run eval:canary   # investigate failing case'
+    }
+}
+
+# ── Section 4: skill-checker -All ───────────────────────────────────────────
+Write-Banner "4. skill-checker -All" "Cyan"
+$checkerPath = Join-Path $Repo 'plugin\skills\skill-checker\check-skill.ps1'
+if (Test-Path $checkerPath) {
+    $ckOut = & pwsh -NoProfile -File $checkerPath -All -Root $Repo 2>&1
+    $ckExit = $LASTEXITCODE
+    if ($ckExit -eq 0) {
+        if (-not $Json) { Write-Host "  ✅ all skills compliant" -ForegroundColor Green }
+        Add-Section 'skill-checker' 'green' 'all skills pass blueprint' ''
+    } else {
+        if (-not $Json) { Write-Host "  ⚠️  blueprint violations (exit=$ckExit)" -ForegroundColor Yellow }
+        Add-Section 'skill-checker' 'yellow' "exit=$ckExit" 'pwsh plugin/skills/skill-checker/check-skill.ps1 -All   # review output'
+    }
+} else {
+    Add-Section 'skill-checker' 'red' 'check-skill.ps1 not found' "Restore plugin/skills/skill-checker/check-skill.ps1"
+}
+
+# ── Section 5: Live-install drift ───────────────────────────────────────────
+Write-Banner "5. live-install drift" "Cyan"
+$liveSkill = Join-Path $userHome '.copilot\m-skills\kushi\SKILL.md'
+$agentFile = Join-Path $Repo 'plugin\agents\kushi.agent.md'
+$metaPath = Join-Path $userHome '.copilot\m-skills\skills-metadata.json'
+$repoVersion = $null
+try { $repoVersion = (Get-Content -Raw (Join-Path $Repo 'package.json') | ConvertFrom-Json).version } catch {}
+$liveVersion = $null
+if (Test-Path $metaPath) {
+    try {
+        $m = Get-Content -Raw $metaPath | ConvertFrom-Json
+        $k = $m | Where-Object { $_.name -eq 'kushi' } | Select-Object -First 1
+        if ($k -and $k.id -match '^kushi-([\d\.]+)$') { $liveVersion = $Matches[1] }
+    } catch {}
+}
+if (-not (Test-Path $liveSkill)) {
+    if (-not $Json) { Write-Host "  ℹ️  no live install (skipped)" -ForegroundColor Gray }
+    Add-Section 'live-install' 'green' 'no live install present' ''
+} elseif ($liveVersion -and $repoVersion -and $liveVersion -ne $repoVersion) {
+    $msg = "live=v$liveVersion repo=v$repoVersion (skew expected)"
+    if (-not $Json) { Write-Host "  ⚠️  $msg" -ForegroundColor Yellow }
+    Add-Section 'live-install' 'yellow' $msg "npx kushi-agents@$repoVersion --clawpilot --force"
+} else {
+    $a = (Get-FileHash $liveSkill -Algorithm SHA256).Hash
+    $b = (Get-FileHash $agentFile -Algorithm SHA256).Hash
+    if ($a -eq $b) {
+        if (-not $Json) { Write-Host "  ✅ live SKILL.md matches repo" -ForegroundColor Green }
+        Add-Section 'live-install' 'green' 'live SKILL.md byte-identical to repo' ''
+    } else {
+        # If the live install file is older than the repo file, the user simply
+        # edited the source after their last install — that's expected mid-dev,
+        # not actionable from inside the repo.
+        $liveOlder = $false
+        try {
+            if ((Get-Item $liveSkill).LastWriteTimeUtc -lt (Get-Item $agentFile).LastWriteTimeUtc) { $liveOlder = $true }
+        } catch {}
+        if ($liveOlder) {
+            if (-not $Json) { Write-Host "  ℹ️  live SKILL.md older than repo (expected mid-dev)" -ForegroundColor Gray }
+            Add-Section 'live-install' 'green' 'live install older than repo (expected mid-dev)' ''
+        } else {
+            if (-not $Json) { Write-Host "  ⚠️  live SKILL.md drifted on SAME version" -ForegroundColor Yellow }
+            Add-Section 'live-install' 'yellow' 'drift on same version' "npx kushi-agents@$repoVersion --clawpilot --force"
+        }
+    }
+}
+
+# ── Section 6: Global wiki shape ────────────────────────────────────────────
+Write-Banner "6. global wiki shape" "Cyan"
+$globalRoot = $env:KUSHI_GLOBAL_ROOT
+if (-not $globalRoot) { $globalRoot = Join-Path $userHome '.kushi-global' }
+if (-not (Test-Path $globalRoot)) {
+    if (-not $Json) { Write-Host "  ℹ️  no global wiki yet (kushi global init to create)" -ForegroundColor Gray }
+    Add-Section 'global-wiki' 'green' 'not initialized (optional)' ''
+} else {
+    $gs = Join-Path $globalRoot 'State'
+    $needs = @()
+    if (-not (Test-Path $gs)) { $needs += 'State/' }
+    foreach ($req in 'index.md','log.md') {
+        if ($gs -and -not (Test-Path (Join-Path $gs $req))) { $needs += "State/$req" }
+    }
+    if ($needs.Count -eq 0) {
+        if (-not $Json) { Write-Host "  ✅ scaffold OK at $globalRoot" -ForegroundColor Green }
+        Add-Section 'global-wiki' 'green' "scaffold OK at $globalRoot" ''
+    } else {
+        if (-not $Json) { Write-Host "  ⚠️  missing: $($needs -join ', ')" -ForegroundColor Yellow }
+        Add-Section 'global-wiki' 'yellow' "missing: $($needs -join ', ')" 'kushi global init   # repair scaffold'
+    }
+}
+
+# ── Summary ribbon ──────────────────────────────────────────────────────────
+$greenCount  = @($sections | Where-Object { $_.status -eq 'green'  }).Count
+$yellowCount = @($sections | Where-Object { $_.status -eq 'yellow' }).Count
+$redCount    = @($sections | Where-Object { $_.status -eq 'red'    }).Count
+
+if ($Json) {
+    [PSCustomObject]@{
+        sections = $sections
+        summary = [PSCustomObject]@{ green = $greenCount; yellow = $yellowCount; red = $redCount }
+    } | ConvertTo-Json -Depth 6
+} else {
+    Write-Host ""
+    if ($redCount -gt 0) {
+        Write-Host "── RED ($redCount red, $yellowCount yellow, $greenCount green) ──" -ForegroundColor Red
+    } elseif ($yellowCount -gt 0) {
+        Write-Host "── YELLOW ($yellowCount yellow, $greenCount green) ──" -ForegroundColor Yellow
+    } else {
+        Write-Host "── GREEN (all $greenCount sections pass) ──" -ForegroundColor Green
+    }
+    foreach ($s in $sections | Where-Object { $_.status -ne 'green' }) {
+        if ($s.fix) {
+            Write-Host ("  Fix [{0}]: {1}" -f $s.name, $s.fix) -ForegroundColor Cyan
+        }
+    }
+    Write-Host ""
+}
+
+if ($redCount -gt 0) { exit 1 }
+if ($Strict -and $yellowCount -gt 0) { exit 1 }
+exit 0

package/plugin/skills/doctor/evals/evals.json

@@ -0,0 +1,28 @@
+{
+  "skill": "doctor",
+  "version": "1.0.0",
+  "description": "doctor.ps1 ships in the skill folder, is parseable, and the SKILL.md is present.",
+  "cases": [
+    {
+      "id": "doctor-skill-md-exists",
+      "name": "SKILL.md is present and parseable",
+      "input": "verify doctor SKILL.md exists",
+      "canary": true,
+      "grader_type": "script",
+      "expected_assertions": [
+        { "type": "file-exists", "path": "plugin/skills/doctor/SKILL.md" },
+        { "type": "file-exists", "path": "plugin/skills/doctor/doctor.ps1" }
+      ]
+    },
+    {
+      "id": "doctor-doctrine-exists",
+      "name": "system-health doctrine ships alongside the skill",
+      "input": "verify doctor doctrine exists",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        { "type": "file-exists", "path": "plugin/instructions/system-health.instructions.md" }
+      ]
+    }
+  ]
+}

package/plugin/skills/self-check/SKILL.md

@@ -77,6 +77,7 @@ Checks split into **core** (always run) and **deep** (opt-in).
 | D38.parallel | Parallel execution (v5.2.0+) | `parallel-execution.instructions.md` exists, `refresh-project/SKILL.md` references parallel dispatch, doctrine documents deterministic output ordering. Sub-checks: `D38.parallel-doctrine-exists`, `D38.refresh-supports-parallel`, `D38.deterministic-order`. |
 | D39.otel | OpenTelemetry export (v5.2.0+) | `otel.instructions.md` exists, `Emit-OtelSpan.ps1` helper exists, helper short-circuits when `KUSHI_OTEL_ENDPOINT` is unset. Sub-checks: `D39.otel-doctrine-exists`, `D39.otel-helper-exists`, `D39.otel-noop-when-unset`. |
 | D40.global-wiki | Global wiki + multi-wiki routing (v5.3.0+) | `global-wiki.instructions.md` + `multi-wiki-routing.instructions.md` both exist; `src/global-wiki.mjs` exports the init/promote surface; resolved `$KUSHI_GLOBAL_ROOT`'s `State/` (when initialized) carries `scope: global` frontmatter on all root pages; no `> [!warning] potential-customer-leak` callouts are unresolved. Sub-checks: `D40.global-wiki-doctrine-exists`, `D40.routing-doctrine-exists`, `D40.global-wiki-module-exists`, `D40.promote-module-exists`, `D40.global-wiki-shape`, `D40.no-customer-leak`. |
+| D41.stabilization | v5.4.0 stabilization + first-run polish | `plugin/skills/doctor/SKILL.md` + `doctor.ps1` ship; `docs/quickstart.md` exists and is ≤200 lines; `docs/migration/v4-to-v5.md` exists; `docs/audits/v5.4.0-soak-fixture.md` exists and mentions all 10 soak steps; `.github/workflows/pr-checks.yml` invokes both self-check and skill-checker with `-StrictExit`. Sub-checks: `D41.doctor-exists`, `D41.quickstart-exists`, `D41.migration-notes-exist`, `D41.soak-audit-exists`, `D41.pr-checks-strict`. |
 | **CSC weekly-layout checks (kushi v4.9.0)** | | gated on `Resolve-EngagementRoots` — no-ops on the kushi repo itself. |
 | D11.csc | CSC entity coverage + depth | every `Evidence/<alias>/<source>/weekly/*-csc.md` has ≥ 1 entity heading; per-source minimum bullet count + populated-section count (meetings 25/6, email 8/4, teams 6/3, onenote 10/4, sharepoint 8/3, crm 12/5, ado 8/4). Coverage-Notes-only blocks (low-signal escape) are exempt. |
 | D12.csc | CSC section order | every entity block's `###` section headings appear in the canonical order: Participants → Topics → Q&A → Who Said What → Decisions → Dates & Numbers → Action Items → Next Steps → Open Questions → Risks → Customer Asks → Artifacts → Coverage Notes. |