kushi-agents 5.0.4 → 5.2.0

package/plugin/skills/lint-state/lint.ps1

@@ -0,0 +1,218 @@
+<#
+.SYNOPSIS
+lint-state — runs wiki-lint checks against a project's State/ directory.
+
+.DESCRIPTION
+Implements the finding classes defined in wiki-lint.instructions.md:
+  - contradiction-flagged
+  - stale-claim
+  - orphan-page
+  - missing-cross-ref
+  - data-gap
+
+Writes a dated lint report to State/reports/, appends to State/log.md, updates
+State/index.md "Last touched" pointer.
+
+.PARAMETER StateDir
+Path to the State/ directory to lint.
+
+.PARAMETER GraphFile
+Optional path to project-graph.json for missing-cross-ref checks.
+
+.PARAMETER Quiet
+Suppress console output (for programmatic use).
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)][string]$StateDir,
+    [string]$GraphFile,
+    [switch]$Quiet
+)
+
+$ErrorActionPreference = 'Stop'
+$findings = @()
+
+# --- Helpers ---
+function Add-LintFinding {
+    param([string]$Class, [string]$Severity, [string]$Entity, [string]$Description, [string]$File, [int]$Line, [string]$Fix)
+    $script:findings += [PSCustomObject]@{
+        class       = $Class
+        severity    = $Severity
+        entity      = $Entity
+        description = $Description
+        file        = $File
+        line        = $Line
+        fix         = $Fix
+    }
+}
+
+# --- Check 1: contradiction-flagged ---
+$stateFiles = Get-ChildItem -Path $StateDir -Recurse -Filter '*.md' -ErrorAction SilentlyContinue
+foreach ($f in $stateFiles) {
+    $lines = Get-Content -Path $f.FullName -ErrorAction SilentlyContinue
+    for ($i = 0; $i -lt $lines.Count; $i++) {
+        if ($lines[$i] -match '^\s*>\s*\[!warning\]\s*Contradicted') {
+            $entity = $f.BaseName -replace '-', ' '
+            Add-LintFinding 'contradiction-flagged' 'warning' $entity "Unresolved contradiction callout" $f.FullName ($i + 1) "Review both values, pick the correct one. Delete callout pair and keep winner, or add <!-- kushi:human-override --> to prevent auto-resolve."
+        }
+    }
+}
+
+# --- Check 2: stale-claim ---
+$staleDays = 60
+$now = Get-Date
+foreach ($f in $stateFiles) {
+    $content = Get-Content -Raw $f.FullName -ErrorAction SilentlyContinue
+    if (-not $content) { continue }
+    $citations = [regex]::Matches($content, '\[source:[^\]]*\xB7\s*(\d{4}-\d{2}-\d{2})\]')
+    if ($citations.Count -eq 0) { continue }
+    $newestDate = $null
+    foreach ($m in $citations) {
+        try {
+            $d = [datetime]::ParseExact($m.Groups[1].Value, 'yyyy-MM-dd', $null)
+            if (-not $newestDate -or $d -gt $newestDate) { $newestDate = $d }
+        } catch {}
+    }
+    if ($newestDate -and ($now - $newestDate).TotalDays -gt $staleDays) {
+        $entity = $f.BaseName -replace '-', ' '
+        Add-LintFinding 'stale-claim' 'warning' $entity "Newest citation is $([math]::Round(($now - $newestDate).TotalDays)) days old (threshold: $staleDays)" $f.FullName 0 "Run '@Kushi refresh <project>' then '@Kushi state <project>' to pull fresh evidence. If claim is still valid, add a corroborating citation from a recent source."
+    }
+}
+
+# --- Check 3: orphan-page ---
+$indexFile = Join-Path $StateDir 'index.md'
+$indexContent = ''
+if (Test-Path $indexFile) { $indexContent = Get-Content -Raw $indexFile }
+$allPageContent = ''
+foreach ($f in $stateFiles) {
+    if ($f.FullName -ne (Resolve-Path $indexFile -ErrorAction SilentlyContinue)) {
+        $allPageContent += (Get-Content -Raw $f.FullName -ErrorAction SilentlyContinue) + "`n"
+    }
+}
+foreach ($f in $stateFiles) {
+    $content = Get-Content -Raw $f.FullName -ErrorAction SilentlyContinue
+    if ($content -notmatch 'kushi_state_page:\s*true') { continue }
+    $slug = $f.BaseName
+    $relPath = $f.FullName.Replace($StateDir, '').TrimStart('\', '/') -replace '\\', '/'
+    if ($indexContent -notmatch [regex]::Escape($slug) -and $allPageContent -notmatch [regex]::Escape($slug)) {
+        Add-LintFinding 'orphan-page' 'warning' $slug "Page not linked from index.md or any sibling" $f.FullName 0 "Add [[$(Split-Path $relPath -Parent)/$slug]] to index.md under the correct category heading, or delete this page if generated in error."
+    }
+}
+
+# --- Check 4: missing-cross-ref ---
+if ($GraphFile -and (Test-Path $GraphFile)) {
+    try {
+        $graph = Get-Content -Raw $GraphFile | ConvertFrom-Json
+        $entityNames = @()
+        if ($graph.nodes) { $entityNames = $graph.nodes | ForEach-Object { $_.name } | Where-Object { $_ } }
+        foreach ($f in $stateFiles) {
+            $content = Get-Content -Raw $f.FullName -ErrorAction SilentlyContinue
+            if ($content -notmatch 'kushi_state_page:\s*true') { continue }
+            foreach ($name in $entityNames) {
+                if ($name.Length -lt 3) { continue }
+                if ($content -match [regex]::Escape($name) -and $content -notmatch "entity_ids:.*$([regex]::Escape($name))" -and $content -notmatch "related:.*$([regex]::Escape($name))") {
+                    # Check frontmatter more carefully
+                    if ($content -match '(?ms)^---\r?\n(.*?)\r?\n---') {
+                        $fm = $Matches[1]
+                        if ($fm -notmatch [regex]::Escape($name)) {
+                            Add-LintFinding 'missing-cross-ref' 'info' ($f.BaseName -replace '-',' ') "Entity '$name' mentioned in body but not in frontmatter" $f.FullName 0 "Add to related: array in front-matter."
+                        }
+                    }
+                }
+            }
+        }
+    } catch {
+        Write-Warning "Could not parse graph file: $_"
+    }
+}
+
+# --- Check 5: data-gap ---
+foreach ($f in $stateFiles) {
+    $content = Get-Content -Raw $f.FullName -ErrorAction SilentlyContinue
+    if ($content -notmatch 'kushi_state_page:\s*true') { continue }
+    $lines = Get-Content -Path $f.FullName
+    for ($i = 0; $i -lt $lines.Count; $i++) {
+        if ($lines[$i] -match '^#{2,3}\s+(.+)$') {
+            $heading = $Matches[1]
+            # Look at content until next heading or EOF
+            $bodyLines = @()
+            for ($j = $i + 1; $j -lt $lines.Count; $j++) {
+                if ($lines[$j] -match '^#{2,3}\s+') { break }
+                if ($lines[$j].Trim() -and $lines[$j].Trim() -ne '<!-- TODO -->' -and $lines[$j].Trim() -ne '<!-- TODO(retrofit) -->') {
+                    $bodyLines += $lines[$j]
+                }
+            }
+            if ($bodyLines.Count -lt 2 -and $heading -notmatch '^(State Log|State Index|Review Queue)') {
+                Add-LintFinding 'data-gap' 'info' ($f.BaseName -replace '-',' ') "Section '$heading' has no meaningful content" $f.FullName ($i + 1) "Run '@Kushi refresh <project>' to pull evidence for this section, or remove the header if not applicable."
+            }
+        }
+    }
+}
+
+# --- Generate report ---
+$reportsDir = Join-Path $StateDir 'reports'
+if (-not (Test-Path $reportsDir)) { New-Item -Path $reportsDir -ItemType Directory -Force | Out-Null }
+
+$dateStr = Get-Date -Format 'yyyy-MM-dd'
+$reportFile = Join-Path $reportsDir "lint-$dateStr.md"
+$timestamp = Get-Date -Format 'yyyy-MM-ddTHH:mm:ssZ'
+
+$classCounts = @{}
+foreach ($f2 in $findings) {
+    if (-not $classCounts.ContainsKey($f2.class)) { $classCounts[$f2.class] = 0 }
+    $classCounts[$f2.class]++
+}
+
+$report = @"
+---
+generated_at: "$timestamp"
+generated_by: "lint-state v1.0.0"
+findings_count: $($findings.Count)
+---
+
+# Lint Report — $dateStr
+
+## Summary
+
+| Class | Count | Severity |
+|---|---|---|
+"@
+
+$classOrder = @('contradiction-flagged','stale-claim','orphan-page','missing-cross-ref','data-gap')
+foreach ($cls in $classOrder) {
+    $count = if ($classCounts.ContainsKey($cls)) { $classCounts[$cls] } else { 0 }
+    $sev = if ($cls -match 'contradiction|stale|orphan') { 'warning' } else { 'info' }
+    $report += "| $cls | $count | $sev |`n"
+}
+
+$report += "`n**Total findings: $($findings.Count)**`n`n## Findings`n"
+
+foreach ($f2 in $findings) {
+    $report += "`n### $($f2.class): $($f2.entity) — $($f2.description)`n`n"
+    $report += "**File:** ``$($f2.file)```n"
+    if ($f2.line -gt 0) { $report += "**Line:** $($f2.line)`n" }
+    $report += "**Fix:** $($f2.fix)`n"
+}
+
+Set-Content -Path $reportFile -Value $report -Encoding utf8NoBOM
+
+# --- Update log + index ---
+$sharedDir = Join-Path $PSScriptRoot '..\_shared'
+$appendLog = Join-Path $sharedDir 'Append-StateLog.ps1'
+$updateIndex = Join-Path $sharedDir 'Update-StateIndex.ps1'
+
+if (Test-Path $appendLog) {
+    & $appendLog -StateDir $StateDir -Op 'lint-state' -Title "Lint pass ($($findings.Count) findings)" -Summary "Classes: $(($classCounts.Keys | Sort-Object | ForEach-Object { "$_=$($classCounts[$_])" }) -join ', ')" -Sources "State/**/*.md"
+}
+if (Test-Path $updateIndex) {
+    & $updateIndex -StateDir $StateDir -Op 'lint-state'
+}
+
+# --- Console output ---
+if (-not $Quiet) {
+    $breakdown = ($classCounts.Keys | Sort-Object | ForEach-Object { "$_=$($classCounts[$_])" }) -join ', '
+    Write-Host "lint-state: $($findings.Count) findings ($breakdown). Report: $reportFile"
+}
+
+# Return findings as output for programmatic use
+$findings

package/plugin/skills/refresh-project/SKILL.md

@@ -91,6 +91,8 @@ After drain, proceed to Step 2 even if some markers remain — the orchestrator
 
 ### Step 2 — Per-source dispatch
 
+> **v5.2.0 parallel dispatch**: By default, enabled sources run in parallel (up to `parallel.max_workers`, default 4). Pass `--sequential` to force serial execution. See `parallel-execution.instructions.md`.
+
 For each enabled source (or just the requested one), call its `pull-<source>` skill with the effective window.
 
 **OneNote pre-dispatch gate (kushi v3.10.0+, HARD):** Before invoking `pull-onenote`, run the browser-URL completeness check:
@@ -200,10 +202,12 @@ Re-running refresh with the same window is safe:
 - "pull `<X>` since `<date>`"
 - "refresh `<X>` last `<N>` days"
 - "backfill `<X>` from `<from>` to `<to>`"
-## References (v4.4.7)
-
-- Name → ID resolution (any source) follows `..\..\instructions\fuzzy-disambiguation.instructions.md`.
-- After each per-source pull, run the gate per `..\..\instructions\per-source-verification-gate.instructions.md` (retry once → FOLLOW-UPS.md on failure).
+## References (v4.4.7)
+
+- Name → ID resolution (any source) follows `..\..\instructions\fuzzy-disambiguation.instructions.md`.
+- After each per-source pull, run the gate per `..\..\instructions\per-source-verification-gate.instructions.md` (retry once → FOLLOW-UPS.md on failure).
+- Parallel dispatch follows `..\..\instructions\parallel-execution.instructions.md` (v5.2.0+).
+- Post-pull hooks fired per source via `..\..\skills\_shared\Invoke-Hooks.ps1` (v5.2.0+).
 
 
 ## Issue Recovery

package/plugin/skills/schema-evolve/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: "schema-evolve"
+version: "1.0.0"
+description: "USE WHEN the user says 'from now on always do X', 'remember this rule', 'kushi remember <rule>', or wants to teach kushi a project-specific convention that persists across runs. DO NOT USE for one-time instructions (just answer inline) or for modifying doctrine (edit the .instructions.md file directly). Capability: captures user-stated conventions to Evidence/<alias>/State/CLAUDE.md, reads them back at the start of build-state/ask-project/refresh runs."
+---
+
+# Skill: schema-evolve
+
+Captures user-stated project conventions and persists them to `Evidence/<alias>/State/CLAUDE.md` so future runs respect them automatically.
+
+## Triggers
+
+- "from now on always do X for this project"
+- "remember that Y means Z"
+- `kushi remember <rule>` (CLI verb)
+- "for this project, always treat A as B"
+- "never include X in summaries for this project"
+
+## Inputs
+
+- `<rule>` — free-text convention statement.
+- `<project>` — engagement name (resolved from context or explicit).
+
+## Procedure
+
+1. **Resolve project** — identify the target project via fuzzy match or current context.
+2. **Parse rule** — extract the convention from user's statement. Normalize to declarative form.
+3. **Validate against doctrine** — check if the rule conflicts with hard doctrine (WorkIQ-only, CSC format, etc.). If conflict: warn user, explain why, do NOT persist.
+4. **Write to CLAUDE.md** — append the rule with timestamp + scope metadata to `Evidence/<alias>/State/CLAUDE.md`.
+5. **Confirm** — echo back the persisted rule and explain when it will be applied.
+
+## Step checklist
+
+- [ ] Step 1 — Resolve project + State path
+- [ ] Step 2 — Parse + validate rule
+- [ ] Step 3 — Append to CLAUDE.md
+- [ ] Step 4 — Confirm to user
+
+### Step 1 — Resolve project
+
+Resolve `<engagement-root>/<project>/Evidence/<alias>/State/`. If CLAUDE.md doesn't exist, create it with the v5.0.0 header:
+
+```markdown
+---
+kushi_state_page: true
+---
+
+# CLAUDE.md — Project Conventions
+
+Rules captured via `schema-evolve` skill. Read by build-state, ask-project, refresh-project at run start.
+```
+
+### Step 2 — Parse + validate
+
+Normalize user's statement:
+- "from now on always X" → "Always X"
+- "never do Y" → "Never Y"
+- "treat A as B" → "Treat A as B"
+
+Validate: if the rule would override hard doctrine (`workiq-only`, `verbatim-by-default`, `csc` format), reject with explanation.
+
+### Step 3 — Append to CLAUDE.md
+
+Append after existing content:
+
+```markdown
+## Rule: <short-title>
+
+- **Added**: <ISO-8601 timestamp>
+- **Scope**: project
+- **Source**: user (natural language)
+
+<normalized rule text>
+```
+
+### Step 4 — Confirm
+
+Print:
+> ✅ Rule captured: "<rule>"
+> Applied to: <project> (project scope)
+> Active in: build-state, ask-project, refresh-project
+
+## Gotchas
+
+1. **Hard doctrine override**: Rules CANNOT override WorkIQ-only, CSC format, verbatim-by-default, or evidence layout. Warn and refuse.
+2. **Duplicate rules**: If a near-identical rule exists, update the existing one (bump timestamp) rather than duplicating.
+3. **CLAUDE.md missing**: Create it with proper frontmatter on first rule capture.
+4. **No evidence modification**: Rules affect interpretation/presentation only — never modify raw evidence files.
+5. **Scope creep**: v5.2.0 is project-scope only. Don't promise global scope.
+
+## Validation loop
+
+After writing:
+1. Re-read `CLAUDE.md` — verify the new rule appears.
+2. Parse all rules — verify valid structure (heading, metadata, text).
+3. Run self-check: `pwsh plugin/skills/self-check/run.ps1 -Targeted schema-evolve`
+
+## References
+
+- `schema-evolve.instructions.md` — doctrine for convention persistence
+- `karpathy-state-layout.instructions.md` — CLAUDE.md role in State layout
+- `living-wiki.instructions.md` — incremental State maintenance
+
+## Issue Recovery
+
+When this skill exposes a reusable defect (doctrine gap, missing cross-reference), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.

package/plugin/skills/schema-evolve/evals/evals.json

@@ -0,0 +1,37 @@
+{
+  "skill": "schema-evolve",
+  "cases": [
+    {
+      "id": "schema-evolve-capture",
+      "name": "Captures a user rule to CLAUDE.md",
+      "input": "kushi remember always use 'HCA' not 'Healthcare Accelerator' in summaries",
+      "expected_assertions": [
+        { "type": "contains", "value": "CLAUDE.md" },
+        { "type": "contains", "value": "Rule" },
+        { "type": "contains", "value": "HCA" }
+      ],
+      "grader_type": "script"
+    },
+    {
+      "id": "schema-evolve-doctrine-conflict",
+      "name": "Rejects rule that conflicts with hard doctrine",
+      "input": "kushi remember never use WorkIQ, always use Graph API directly",
+      "expected_assertions": [
+        { "type": "contains", "value": "conflict" },
+        { "type": "contains", "value": "WorkIQ" },
+        { "type": "not_contains", "value": "Rule captured" }
+      ],
+      "grader_type": "script"
+    },
+    {
+      "id": "schema-evolve-natural-language",
+      "name": "Auto-detects convention from natural language",
+      "input": "from now on for this project always treat John as the EM",
+      "expected_assertions": [
+        { "type": "contains", "value": "John" },
+        { "type": "contains", "value": "rule" }
+      ],
+      "grader_type": "script"
+    }
+  ]
+}

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

@@ -71,6 +71,11 @@ Checks split into **core** (always run) and **deep** (opt-in).
 | D32.multi-host | Multi-host install integrity | validates `src/multi-host.mjs` exports + `bin/cli.mjs` flag handling, then performs a temp-dir dry-run install for BOTH supported hosts (Clawpilot + VS Code Chat) under a fake `$HOME` in `$env:TEMP`. Asserts SKILL.md + agent file + skills/ + prompts/ + skills-metadata.json with a kushi entry are present, then asserts a clean uninstall. NEVER touches the real `~/.copilot/` or `~/.vscode/`. See `multi-host-install.instructions.md`. |
 | D33.evals | Skill evals framework integrity | every `plugin/skills/<name>/` (except `eval`) ships `evals/evals.json` with ≥ 2 cases and ≥ 1 assertion per case; the runner (`plugin/skills/eval/run-evals.ps1`) and schema (`plugin/skills/eval/evals.schema.json`) are present; `evals/baseline.json` exists (warn-only). Six sub-checks: `D33.evals-exist`, `D33.evals-schema`, `D33.evals-min-cases`, `D33.evals-have-assertions`, `D33.eval-runner-exists`, `D33.baseline-exists`. See `skill-evals.instructions.md`. |
 | D34.creator-conformance | skill-creator + skill-checker harness integrity (v5.0.4+) | validates `scaffold.ps1` + `check-skill.ps1` ship and are parseable; every skill carrying the `.created-by-skill-creator` marker passes `check-skill --lint` clean; `check-skill --all --retrofit --dry-run` shows no non-additive gaps; the dogfood report at `docs/audits/v5.0.4-skill-creator-dogfood.md` is fresh (≤14 days). Five sub-checks: `D34.skill-creator-exists`, `D34.skill-checker-exists`, `D34.creator-output-conforms`, `D34.retrofit-clean`, `D34.dogfood-report-fresh`. See `skill-authoring.instructions.md`. |
+| D35.log | State log (v5.1.0+) | `State/log.md` exists, `## [` headings match canonical format, timestamps reverse-chronological. Sub-checks: `D35.log-exists`, `D35.log-format`, `D35.log-monotonic`. |
+| D36.contradictions | Contradictions (v5.1.0+) | `> [!warning] Contradicted` callouts well-formed, `_review-queue.md` fresh, `<!-- kushi:auto -->` fences balanced. Sub-checks: `D36.callout-syntax`, `D36.review-queue-fresh`, `D36.no-silent-overwrite`. |
+| D37.hooks | Hooks system (v5.2.0+) | `hooks.instructions.md` exists, `Invoke-Hooks.ps1` helper exists, hook-templates/ has ≥2 templates, any `hooks-log.md` uses canonical heading format. Sub-checks: `D37.hooks-doctrine-exists`, `D37.hooks-helper-exists`, `D37.hooks-templates-exist`, `D37.hooks-log-format`. |
+| 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`. |
 | **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. |
@@ -83,7 +88,7 @@ Checks split into **core** (always run) and **deep** (opt-in).
 | D19.csc | CSC legacy write guard | WARN if `snapshot/` or `stream/` contains a file modified after the v4.9.0 release date (2026-05-26). Reads of legacy layouts remain supported. |
 | **v5.0.0 cross-source / state / dashboard / tour checks** | | gated on `Resolve-EngagementRoots` — no-ops on the kushi repo itself. |
 | D20.graph | Entity-graph well-formed | `Evidence/_graph/project-graph.json`: valid JSON, has `schema/project/generated_at/nodes/edges`, every edge `kind` is in the closed taxonomy (`references`/`decides`/`action-item-tracks`/`discusses`/`produced-by`/`follow-up-of`/`same-thread`/`participant-of`), every edge endpoint resolves to a node. See `entity-graph.instructions.md`. |
-| D21.state | Karpathy State layout | when any `State/**/*.md` has front-matter `kushi_state_page: true`, the sibling `index.md`, `log.md`, `CLAUDE.md`, `AGENTS.md` MUST exist, `CLAUDE.md` and `AGENTS.md` MUST be byte-identical, and every v5 page MUST live under one of the closed-set category folders (`people/`, `opportunities/`, `adoworkitems/`, `decisions/`, `risks/`, `customerasks/`, `meetings/`, `artifacts/`). See `karpathy-state-layout.instructions.md`. |
+| D21.state | Karpathy State layout | `kushi_state_page: true` pages require sibling `index.md`, `log.md`, `CLAUDE.md`, `AGENTS.md`; pages live under closed-set category folders. See `karpathy-state-layout.instructions.md`. |
 | D22.dashboard | Dashboard produced + substituted | when `project-graph.json` exists, `<project>/dashboard.html` MUST exist, MUST NOT still contain the literal `__GRAPH_JSON__` placeholder (would indicate embedder failure), and MUST reference Cytoscape. See `dashboard-artifact.instructions.md`. |
 | D23.tour | Tour citations resolve | every `- **Cite:** [`<path>`]` row in `<project>/State/tour.md` MUST resolve to a real file under `<project>/Evidence/`. See `guided-tour.instructions.md`. |
 
@@ -105,59 +110,7 @@ Checks split into **core** (always run) and **deep** (opt-in).
 
 ## Algorithm (per check)
 
-### C1 — Frontmatter completeness
-
-For each `plugin/skills/<dir>/SKILL.md`: parse YAML frontmatter (text between leading `---` lines). Required keys: `name`, `version`, `description`.
-
-> ⚠️ self-check C1 — Skill `<dir>` is missing required frontmatter key `<key>`. Add it before the first `---` separator.
-
-### C2 — Skill name matches directory
-
-For each skill: `frontmatter.name` (case-insensitive) must equal directory name.
-
-> ⚠️ self-check C2 — Directory `<dir>/` declares `name: "<name>"`. Rename one or the other so they match.
-
-### C3 — Skills inventoried in agent
-
-`plugin/agents/kushi.agent.md` must contain a backtick-wrapped reference to every skill directory name. Look in any markdown table column or any inline `\`<name>\`` token.
-
-> ⚠️ self-check C3 — Skill `<dir>` is not listed in the kushi agent. Suggested row for the routing table:
->
-> `| <verb> | <dir> | <one-line description from frontmatter> |`
-
-### C4 — Prompts route to real skills
-
-For each `plugin/prompts/*.prompt.md`: extract any reference of the form `` `<skill-name>` `` or `delegates to <skill-name>` (case-insensitive). Each must exist as a directory under `plugin/skills/`.
-
-> ⚠️ self-check C4 — Prompt `<file>` references skill `<name>` which does not exist under `plugin/skills/`. Either create the skill or update the prompt.
-
-### C5 — Instructions referenced
-
-For each `plugin/instructions/*.instructions.md`: at least one SKILL.md OR `plugin/agents/kushi.agent.md` must reference it by filename (with or without path).
-
-> ⚠️ self-check C5 — Instruction `<file>` is not referenced anywhere. Either delete it or add a "## References" line to the relevant skill(s).
-
-### C6 — Cross-links resolve
-
-For every markdown link with a relative target (`](./...)`, `](../...)`, or `](path/...)` not starting with `http`) inside `plugin/**/*.md`: target must exist on disk relative to the file containing it.
-
-> ⚠️ self-check C6 — `<source-file>:<line>` links to `<target>` which does not exist. Update or remove the link.
-
-### C7 — Verbs table matches prompts
-
-`README.md` contains a "Verbs" / "Quick start" table. Every `plugin/prompts/<verb>.prompt.md` must have a row in that table; every row in the table must have a corresponding prompt file.
-
-> ⚠️ self-check C7 — Verb `<v>` exists as `plugin/prompts/<v>.prompt.md` but is missing from README's verbs table. Suggested row:
->
-> `| \`<v>\` | <default window> | <one-line description> |`
-
-### C8 — Distribution layout matches docs
-
-`docs/reference/where-things-live.md` contains an ASCII tree of `plugin/`. Every top-level subdirectory and notable file under `plugin/` must appear; every entry in the tree must exist on disk.
-
-> ⚠️ self-check C8 — `plugin/<x>` exists but is missing from the docs/reference/where-things-live.md tree. Add an entry under section "1. This repo".
-
-### D-checks: see `run.ps1` for the exact regexes.
+> Load on trigger: see [`references/algorithm.md`](references/algorithm.md) for per-check pseudocode and finding templates (C1–C8, D-checks).
 
 ## Validation rules
 
@@ -202,4 +155,8 @@ This skill is not invoked by `@Kushi <verb>` — it's a meta-skill. Triggers:
 ## References
 
 - `instructions/citation-ledger.instructions.md` (findings cite source files / line numbers)
-- `instructions/side-by-side-config.instructions.md` (D6 enforces this rule for skills that read/write user config)
+- `instructions/side-by-side-config.instructions.md` (D6 enforces this rule for skills that read/write user config)
+- `instructions/hooks.instructions.md` (D37 validates hooks system)
+- `instructions/parallel-execution.instructions.md` (D38 validates parallel dispatch)
+- `instructions/otel.instructions.md` (D39 validates OTel export)
+- `instructions/schema-evolve.instructions.md` (D39 validates schema evolution)

package/plugin/skills/self-check/references/algorithm.md

@@ -0,0 +1,55 @@
+# Algorithm (per check)
+
+### C1 — Frontmatter completeness
+
+For each `plugin/skills/<dir>/SKILL.md`: parse YAML frontmatter (text between leading `---` lines). Required keys: `name`, `version`, `description`.
+
+> ⚠️ self-check C1 — Skill `<dir>` is missing required frontmatter key `<key>`. Add it before the first `---` separator.
+
+### C2 — Skill name matches directory
+
+For each skill: `frontmatter.name` (case-insensitive) must equal directory name.
+
+> ⚠️ self-check C2 — Directory `<dir>/` declares `name: "<name>"`. Rename one or the other so they match.
+
+### C3 — Skills inventoried in agent
+
+`plugin/agents/kushi.agent.md` must contain a backtick-wrapped reference to every skill directory name. Look in any markdown table column or any inline `` `<name>` `` token.
+
+> ⚠️ self-check C3 — Skill `<dir>` is not listed in the kushi agent. Suggested row for the routing table:
+>
+> `| <verb> | <dir> | <one-line description from frontmatter> |`
+
+### C4 — Prompts route to real skills
+
+For each `plugin/prompts/*.prompt.md`: extract any reference of the form `` `<skill-name>` `` or `delegates to <skill-name>` (case-insensitive). Each must exist as a directory under `plugin/skills/`.
+
+> ⚠️ self-check C4 — Prompt `<file>` references skill `<name>` which does not exist under `plugin/skills/`. Either create the skill or update the prompt.
+
+### C5 — Instructions referenced
+
+For each `plugin/instructions/*.instructions.md`: at least one SKILL.md OR `plugin/agents/kushi.agent.md` must reference it by filename (with or without path).
+
+> ⚠️ self-check C5 — Instruction `<file>` is not referenced anywhere. Either delete it or add a "## References" line to the relevant skill(s).
+
+### C6 — Cross-links resolve
+
+For every markdown link with a relative target (`](./...)`, `](../...)`, or `](path/...)` not starting with `http`) inside `plugin/**/*.md`: target must exist on disk relative to the file containing it.
+
+> ⚠️ self-check C6 — `<source-file>:<line>` links to `<target>` which does not exist. Update or remove the link.
+
+### C7 — Verbs table matches prompts
+
+`README.md` contains a "Verbs" / "Quick start" table. Every `plugin/prompts/<verb>.prompt.md` must have a row in that table; every row in the table must have a corresponding prompt file.
+
+> ⚠️ self-check C7 — Verb `<v>` exists as `plugin/prompts/<v>.prompt.md` but is missing from README's verbs table. Suggested row:
+>
+> `| \`<v>\` | <default window> | <one-line description> |`
+
+### C8 — Distribution layout matches docs
+
+`docs/reference/where-things-live.md` contains an ASCII tree of `plugin/`. Every top-level subdirectory and notable file under `plugin/` must appear; every entry in the tree must exist on disk.
+
+> ⚠️ self-check C8 — `plugin/<x>` exists but is missing from the docs/reference/where-things-live.md tree. Add an entry under section "1. This repo".
+
+### D-checks: see `run.ps1` for the exact regexes.