kushi-agents 5.1.0 → 5.2.0

package/plugin/skills/_shared/Emit-OtelSpan.ps1

@@ -0,0 +1,111 @@
+<#
+.SYNOPSIS
+Emits an OpenTelemetry span via OTLP/HTTP JSON.
+
+.DESCRIPTION
+Opt-in OTel export. If KUSHI_OTEL_ENDPOINT is unset or empty, this is a
+complete no-op (no HTTP calls, no allocations). Pure PowerShell — no
+external dependencies.
+
+.PARAMETER SpanName
+The span name (e.g., 'kushi.pull', 'kushi.build_state').
+
+.PARAMETER Attributes
+Hashtable of span attributes. Only metadata — never evidence content.
+
+.PARAMETER DurationMs
+Duration in milliseconds (optional — computed from Start if provided).
+
+.PARAMETER Start
+Optional start time [datetime]. Defaults to (now - DurationMs).
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)][string]$SpanName,
+    [hashtable]$Attributes = @{},
+    [int]$DurationMs = 0,
+    [datetime]$Start = [datetime]::MinValue
+)
+
+# No-op guard — zero overhead when endpoint is unset
+$endpoint = $env:KUSHI_OTEL_ENDPOINT
+if (-not $endpoint) { return }
+
+$ErrorActionPreference = 'Continue'
+
+try {
+    # Compute timestamps (nanoseconds since epoch)
+    $now = [DateTimeOffset]::UtcNow
+    if ($Start -eq [datetime]::MinValue) {
+        $startOffset = $now.AddMilliseconds(-$DurationMs)
+    } else {
+        $startOffset = [DateTimeOffset]::new($Start.ToUniversalTime())
+    }
+    $endOffset = $now
+
+    $startNs = ($startOffset.ToUnixTimeMilliseconds() * 1000000).ToString()
+    $endNs = ($endOffset.ToUnixTimeMilliseconds() * 1000000).ToString()
+
+    # Generate trace/span IDs
+    $traceId = [System.Guid]::NewGuid().ToString('N')
+    $spanId = [System.Guid]::NewGuid().ToString('N').Substring(0, 16)
+
+    # Build attributes array
+    $attrArray = @()
+    # Allowed keys only (privacy contract)
+    $allowedKeys = @('project','alias','source','duration_ms','success','evidence_count',
+                     'pages_written','contradictions_flagged','findings_count','entity',
+                     'field','event','hook_type','target','report_path','items_pulled')
+    foreach ($key in $Attributes.Keys) {
+        if ($key -notin $allowedKeys) { continue }
+        $val = $Attributes[$key]
+        $valObj = if ($val -is [bool]) {
+            @{ boolValue = $val }
+        } elseif ($val -is [int] -or $val -is [long] -or $val -is [double]) {
+            @{ intValue = [string]$val }
+        } else {
+            @{ stringValue = [string]$val }
+        }
+        $attrArray += @{ key = $key; value = $valObj }
+    }
+
+    # Get service version
+    $version = '5.2.0'
+    $pkgJson = Join-Path $PSScriptRoot '..\..\..\..\package.json'
+    if (Test-Path $pkgJson) {
+        try { $version = (Get-Content -Raw $pkgJson | ConvertFrom-Json).version } catch {}
+    }
+
+    # Build OTLP payload
+    $payload = @{
+        resourceSpans = @(@{
+            resource = @{
+                attributes = @(
+                    @{ key = 'service.name'; value = @{ stringValue = 'kushi' } }
+                    @{ key = 'service.version'; value = @{ stringValue = $version } }
+                )
+            }
+            scopeSpans = @(@{
+                scope = @{ name = 'kushi'; version = $version }
+                spans = @(@{
+                    traceId = $traceId
+                    spanId = $spanId
+                    name = $SpanName
+                    kind = 1  # SPAN_KIND_INTERNAL
+                    startTimeUnixNano = $startNs
+                    endTimeUnixNano = $endNs
+                    attributes = $attrArray
+                    status = @{
+                        code = if ($Attributes['success'] -eq $false) { 2 } else { 1 }
+                    }
+                })
+            })
+        })
+    }
+
+    $json = $payload | ConvertTo-Json -Depth 20 -Compress
+    Invoke-RestMethod -Uri $endpoint -Method POST -Body $json `
+        -ContentType 'application/json' -TimeoutSec 5 -ErrorAction Stop | Out-Null
+} catch {
+    Write-Warning "OTel export failed (non-blocking): $($_.Exception.Message)"
+}

package/plugin/skills/_shared/Invoke-Hooks.ps1

@@ -0,0 +1,177 @@
+<#
+.SYNOPSIS
+Dispatches hooks for a kushi pipeline event.
+
+.DESCRIPTION
+Idempotent hook dispatcher. Reads .kushi/hooks.yml + .kushi/hooks/*.ps1,
+invokes each configured hook for the given event, captures output/duration,
+and logs results to Evidence/<alias>/State/hooks-log.md.
+
+Failures are warn-only — never blocks the pipeline.
+
+.PARAMETER ProjectRoot
+Path to the project root (contains .kushi/).
+
+.PARAMETER Event
+One of: post-pull, post-state, post-contradiction, post-lint.
+
+.PARAMETER Payload
+Hashtable of event data (serialized to JSON for hooks).
+
+.PARAMETER StateDir
+Path to Evidence/<alias>/State/ for logging.
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)][string]$ProjectRoot,
+    [Parameter(Mandatory)][ValidateSet('post-pull','post-state','post-contradiction','post-lint')][string]$Event,
+    [Parameter(Mandatory)][hashtable]$Payload,
+    [string]$StateDir
+)
+
+$ErrorActionPreference = 'Continue'
+
+$hooksYml = Join-Path $ProjectRoot '.kushi/hooks.yml'
+$hooksDir = Join-Path $ProjectRoot '.kushi/hooks'
+$payloadJson = $Payload | ConvertTo-Json -Depth 10 -Compress
+
+# Collect hook definitions
+$hookDefs = @()
+
+# Parse hooks.yml if present
+if (Test-Path $hooksYml) {
+    $lines = Get-Content -Path $hooksYml -ErrorAction SilentlyContinue
+    $inEvent = $false
+    $eventIndent = 0
+    foreach ($line in $lines) {
+        if ($line -match "^\s*$Event\s*:") {
+            $inEvent = $true
+            $eventIndent = ($line -replace '[^\s].*','').Length
+            continue
+        }
+        if ($inEvent) {
+            # Determine current indent
+            $currentIndent = if ($line -match '^(\s*)') { $Matches[1].Length } else { 0 }
+            # Exit if we hit a line at same/lower indent that's not empty
+            if ($line.Trim() -ne '' -and $currentIndent -le $eventIndent -and $line -notmatch '^\s*#') {
+                $inEvent = $false
+                continue
+            }
+            if ($line -match '^\s*-\s*type:\s*(\w+)') { $currentType = $Matches[1]; continue }
+            if ($line -match '^\s*url:\s*(.+)') {
+                $hookDefs += @{ type = 'webhook'; target = $Matches[1].Trim() }
+            }
+            if ($line -match '^\s*path:\s*(.+)') {
+                $hookDefs += @{ type = 'script'; target = $Matches[1].Trim() }
+            }
+        }
+    }
+}
+
+# Also check for event-named script in hooks dir
+$eventScript = Join-Path $hooksDir "$Event.ps1"
+if ((Test-Path $eventScript) -and -not ($hookDefs | Where-Object { $_.target -eq $eventScript })) {
+    $hookDefs += @{ type = 'script'; target = $eventScript }
+}
+
+if ($hookDefs.Count -eq 0) {
+    Write-Verbose "No hooks configured for event '$Event'"
+    return
+}
+
+# Emit OTel span for each hook invocation
+$emitOtel = Join-Path $PSScriptRoot 'Emit-OtelSpan.ps1'
+
+$results = @()
+foreach ($hook in $hookDefs) {
+    $sw = [System.Diagnostics.Stopwatch]::StartNew()
+    $status = 'success'
+    $output = ''
+
+    try {
+        if ($hook.type -eq 'webhook') {
+            $resp = Invoke-RestMethod -Uri $hook.target -Method POST -Body $payloadJson `
+                -ContentType 'application/json' -TimeoutSec 5 -ErrorAction Stop
+        } elseif ($hook.type -eq 'script') {
+            $scriptPath = if ([System.IO.Path]::IsPathRooted($hook.target)) {
+                $hook.target
+            } else {
+                Join-Path (Resolve-Path $ProjectRoot).Path $hook.target
+            }
+            if (Test-Path $scriptPath) {
+                try {
+                    $output = $payloadJson | & pwsh -NoProfile -Command "try { & '$scriptPath' } catch { Write-Output `$_.Exception.Message; exit 1 }" 2>&1 | Out-String
+                    if ($LASTEXITCODE -ne 0) {
+                        $status = 'failed'
+                    }
+                } catch {
+                    $status = 'failed'
+                    $output = $_.Exception.Message
+                }
+            } else {
+                $status = 'skipped'
+                $output = "Script not found: $scriptPath"
+            }
+        }
+    } catch {
+        $status = 'failed'
+        $output = $_.Exception.Message
+    }
+
+    $sw.Stop()
+    $results += @{
+        hook = $hook
+        status = $status
+        duration_ms = $sw.ElapsedMilliseconds
+        output = $output
+    }
+
+    # Emit OTel span if helper exists
+    if (Test-Path $emitOtel) {
+        $otelAttrs = @{
+            project = $Payload.project ?? ''
+            alias = $Payload.alias ?? ''
+            event = $Event
+            hook_type = $hook.type
+            target = $hook.target
+            duration_ms = $sw.ElapsedMilliseconds
+            success = ($status -eq 'success')
+        }
+        & $emitOtel -SpanName 'kushi.hook.invoked' -Attributes $otelAttrs
+    }
+}
+
+# Write hooks-log.md
+if ($StateDir -and (Test-Path $StateDir)) {
+    $logFile = Join-Path $StateDir 'hooks-log.md'
+    $timestamp = Get-Date -Format 'yyyy-MM-dd HH:mm'
+
+    $entries = @()
+    foreach ($r in $results) {
+        $entry = @"
+
+## [$timestamp] $Event | hook: $($r.hook.target | Split-Path -Leaf)
+
+- status: $($r.status)
+- duration_ms: $($r.duration_ms)
+- target: $($r.hook.target)
+"@
+        if ($r.status -eq 'failed') {
+            $entry += "`n- error: $($r.output)"
+        }
+        $entries += $entry
+    }
+
+    $newContent = $entries -join "`n"
+
+    if (Test-Path $logFile) {
+        $existing = Get-Content -Raw $logFile
+        Set-Content -Path $logFile -Value ($existing + "`n" + $newContent) -Encoding utf8NoBOM
+    } else {
+        $header = "---`nkushi_hooks_log: true`n---`n`n# Hooks Log`n"
+        Set-Content -Path $logFile -Value ($header + $newContent) -Encoding utf8NoBOM
+    }
+}
+
+# Return results for caller inspection
+$results

package/plugin/skills/_shared/hook-templates/console-debug.ps1

@@ -0,0 +1,15 @@
+<#
+.SYNOPSIS
+Hook template: Debug output — prints event payload to console.
+
+.DESCRIPTION
+Copy this file to .kushi/hooks/<event>.ps1 for debugging.
+Prints the full event payload to stdout with timestamp.
+#>
+
+$payload = $input | Out-String
+$timestamp = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'
+
+Write-Output "=== KUSHI HOOK DEBUG [$timestamp] ==="
+Write-Output $payload
+Write-Output "=== END HOOK DEBUG ==="

package/plugin/skills/_shared/hook-templates/teams-notify.ps1

@@ -0,0 +1,47 @@
+<#
+.SYNOPSIS
+Hook template: Posts event to a Microsoft Teams webhook.
+
+.DESCRIPTION
+Copy this file to .kushi/hooks/post-pull.ps1 (or any event name) and
+set $WebhookUrl to your Teams Incoming Webhook URL.
+
+Receives event payload as JSON on stdin.
+#>
+
+# === CONFIGURE THIS ===
+$WebhookUrl = $env:KUSHI_TEAMS_WEBHOOK_URL  # Or hard-code your URL
+
+if (-not $WebhookUrl) {
+    Write-Warning "KUSHI_TEAMS_WEBHOOK_URL not set — skipping Teams notification"
+    exit 0
+}
+
+# Read event payload from stdin
+$payload = $input | Out-String | ConvertFrom-Json
+
+# Build Teams Adaptive Card message
+$card = @{
+    type = 'message'
+    attachments = @(@{
+        contentType = 'application/vnd.microsoft.card.adaptive'
+        content = @{
+            '$schema' = 'http://adaptivecards.io/schemas/adaptive-card.json'
+            type = 'AdaptiveCard'
+            version = '1.4'
+            body = @(
+                @{ type = 'TextBlock'; text = "🔔 Kushi: $($payload.event ?? 'event')"; weight = 'Bolder'; size = 'Medium' }
+                @{ type = 'FactSet'; facts = @(
+                    @{ title = 'Project'; value = $payload.project ?? 'unknown' }
+                    @{ title = 'Source'; value = $payload.source ?? 'n/a' }
+                    @{ title = 'Status'; value = if ($payload.success) { '✅ Success' } else { '⚠️ Issue' } }
+                    @{ title = 'Duration'; value = "$($payload.duration_ms ?? 0)ms" }
+                )}
+            )
+        }
+    })
+}
+
+$json = $card | ConvertTo-Json -Depth 20 -Compress
+Invoke-RestMethod -Uri $WebhookUrl -Method POST -Body $json -ContentType 'application/json' | Out-Null
+Write-Output "Teams notification sent for $($payload.project)"

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

@@ -73,6 +73,9 @@ Checks split into **core** (always run) and **deep** (opt-in).
 | 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. |
@@ -107,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
 
@@ -204,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.