kushi-agents 5.2.0 → 5.4.0

package/plugin/instructions/multi-wiki-routing.instructions.md

@@ -0,0 +1,117 @@
+---
+name: "multi-wiki-routing"
+description: "v5.3.0 — Routing rules for project vs global wiki. ask-project: project-first; augment with global only if project confidence below threshold; --global forces global-first, --project-only suppresses global. build-state: project-only, never auto-promotes to global. lint-state: project-only; kushi lint --global lints global separately. teach: global-first for cross-cutting topics, project for project-specific. Promotion path: explicit kushi promote <project> <page>, never automatic."
+applies_to: "ask-project, build-state, lint-state, teach, promote"
+since: "kushi v5.3.0"
+---
+
+# multi-wiki-routing — doctrine
+
+> **Authored to [agentskills.io](https://agentskills.io/skill-creation/best-practices) spec.**
+> Deltas from source: kushi previously had a single wiki per project. This doctrine formalizes the project↔global routing rules introduced in v5.3.0.
+
+Kushi maintains two kinds of wikis:
+
+| Kind | Path | Scope |
+|---|---|---|
+| **Project** | `Evidence/<alias>/State/` | One engagement only. |
+| **Global** | `$KUSHI_GLOBAL_ROOT` or `~/.kushi-global/State/` | Cross-engagement; per-user. |
+
+Every reader/writer skill MUST be explicit about which it touches.
+
+## Rules (HARD)
+
+### 1. ask-project — project-first, global-augment
+
+Default behavior (`kushi ask <project> <q>`):
+
+1. Resolve the project and run the standard project-scoped answer chain (per `ask-project/SKILL.md`).
+2. Compute the confidence (per `evidence-confidence-ladder.instructions.md`).
+3. **If confidence is `low` (or `medium` with `--global-augment` set in config)** → also query `$KUSHI_GLOBAL_ROOT/State/answers/` for matching topics and append a `## From your global wiki` section, citing each hit with `[global: <page>]`.
+4. **If confidence is `high`** → do NOT consult global (avoid noise).
+
+Flags:
+
+| Flag | Behavior |
+|---|---|
+| `--global` | Reverse the order: search global first, project second. Show provenance `[global]` first, `[project: <alias>]` second. |
+| `--project-only` | Hard-disable global consultation regardless of confidence. |
+| (none) | Default project-first + augment-on-low-confidence. |
+
+Source provenance MUST be visible per citation: `[project: <alias>]` vs `[global]`.
+
+### 2. build-state — project-only
+
+`build-state` writes to `Evidence/<alias>/State/` and **NEVER** writes to the global wiki. There is no auto-promotion path. Even if a fact has appeared in 10 projects, build-state does not move it to global — only the user, via `kushi promote`, does.
+
+### 3. lint-state — project-only by default
+
+- `kushi lint <project>` → lints the project State only. Unchanged from v5.1.0.
+- `kushi lint --global` → lints the global wiki at `$KUSHI_GLOBAL_ROOT/State/` separately. Same finding classes plus `potential-customer-leak` (see `global-wiki.instructions.md`).
+- Lint runs are independent; one does not implicitly run the other.
+
+### 4. teach — global-first for cross-cutting topics
+
+- For **cross-cutting topics** (kushi concepts, doctrines, releases — e.g. "explain confidence ladder", "how does CSC work"): `teach` consults the global wiki FIRST (if a matching page exists in `~/.kushi-global/State/answers/`), then falls back to in-repo doctrine, then to genealogy.
+- For **project-specific topics** ("how did we structure intake for AGCO?"): `teach` declines and suggests `kushi ask <project> <q>` instead — that's an `ask-project` job.
+- Citations distinguish `[global: <page>]` vs `[doctrine: <file>]` vs `[genealogy: <version>]`.
+
+### 5. Promotion path — explicit only
+
+`kushi promote <project> <page>` is the **only** way content moves project → global. See `Promote operation` below.
+
+Auto-promotion is intentionally not supported because:
+
+1. Customer-identifier detection is best-effort; the user must review.
+2. What is "cross-cutting" depends on the consultant, not the machine.
+3. Silent promotion would surprise the user — global is personal space.
+
+### 6. Demotion / removal
+
+There is no `kushi demote` in v5.3.0. To remove a global page the user deletes the file directly and appends a manual `log.md` entry. v6+ MAY add a managed demote verb.
+
+## Promote operation
+
+`kushi promote <project> <page-path>` performs the following, in order:
+
+1. **Resolve source.** Find `<engagement-root>/<project>/Evidence/<alias>/State/<page-path>`. Must exist.
+2. **Read source body + frontmatter.**
+3. **Run identifier scan** against the body. Uses the same heuristics as `schema-evolve`-style detection:
+   - Known customer aliases registered in `.settings.yml` `discovery.project_aliases:` or the alias folder name itself.
+   - The literal project name.
+   - Email addresses with non-Microsoft domains.
+   - High-confidence proper-noun runs that match `<project>` aliases (case-insensitive, word boundaries).
+4. **Build redaction list.** For each hit:
+   - Replace the literal string with `[REDACTED]` in the global copy.
+   - Record `{ pattern, count, line_numbers }` in the redactions list.
+5. **Refuse without `--force`** if the redactions list is non-empty. Print the list with line numbers and the human-review prompt. The user is expected to inspect, then re-run with `--force` (which writes the redacted body and adds a `> [!warning] potential-customer-leak` callout near each redaction site for the lint pass to track).
+6. **Write target.** Path: `$KUSHI_GLOBAL_ROOT/State/answers/<source-slug>.md` (slugify source filename; collisions append `-N`).
+   Frontmatter MUST contain:
+   ```yaml
+   ---
+   kushi_state_page: true
+   scope: global
+   promoted_from: "<project>/<alias>/<relative-source-path>"
+   promoted_at: "<ISO-8601 UTC>"
+   redactions: ["<pattern1>", "<pattern2>"]
+   ---
+   ```
+7. **Add back-link to source.** Append (or update) a callout in the source page:
+   ```markdown
+   > [!info] Promoted to global wiki
+   > <source-slug>.md @ <ISO-8601 UTC> · redactions: <N>
+   ```
+8. **Dual log.** Append a `promote` entry to BOTH:
+   - `<project>/Evidence/<alias>/State/log.md` (op = `promote`, title = `Promoted <slug> to global`).
+   - `$KUSHI_GLOBAL_ROOT/State/log.md` (op = `promote-in`, title = `Imported <slug> from <project>`).
+9. **Print summary** with both file paths.
+
+The operation is **atomic**: if any step fails (redaction refused, write denied, back-link fails), no writes are persisted. The implementation uses a stage-then-commit pattern.
+
+## References
+
+- `global-wiki.instructions.md` — global wiki location + privacy rules
+- `evidence-confidence-ladder.instructions.md` — confidence threshold for routing
+- `living-wiki.instructions.md` — same incremental + contradiction rules apply to both wikis
+- `wiki-lint.instructions.md` — finding classes; v5.3.0 adds `potential-customer-leak`
+- `schema-evolve.instructions.md` — identifier-detection heuristics reused here

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/ask-project/SKILL.md

@@ -72,6 +72,20 @@ When the user passes `--file-back` (or says "file this answer back", "save this
 
 The `--file-back` flag is OPTIONAL. Without it, ask-project behaves exactly as before (read-only, no writes).
 
+## --global / --project-only (v5.3.0+)
+
+Multi-wiki routing flags governed by `multi-wiki-routing.instructions.md`:
+
+| Flag | Behavior |
+|------|----------|
+| *(no flag)* | **Project-first.** Search project `Evidence/<alias>/State/` first; only fall back to the global wiki when project sources are missing/stale or no hit is found. Cite each hit with `[project: <alias>]` or `[global]`. |
+| `--global` | **Global-first.** Search `$KUSHI_GLOBAL_ROOT/State/answers/` first; fall back to the project. Use when you trust the cross-engagement note more than project state. |
+| `--project-only` | **Hard-suppress global.** Never read the global wiki for this question (privacy-sensitive or strictly project-internal). |
+
+Provenance is never silent. Every citation tags `[project: <alias>]` or `[global]`. If the answer mixes both, list each source with its provenance.
+
+The global wiki itself is opt-in (created via `kushi global init`). If it does not exist on disk, all three modes degrade silently to project-only.
+
 ## Inputs
 
 - `<project>` — fuzzy-matched project name. If multiple plausible matches, ask the user.

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