kushi-agents 5.0.4 → 5.2.0

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

@@ -120,7 +120,7 @@ if (-not (Test-Path $pluginDir)) {
     exit 2
 }
 
-$skillDirs = Get-ChildItem $skillsDir -Directory | Sort-Object Name
+$skillDirs = Get-ChildItem $skillsDir -Directory | Where-Object { $_.Name -notmatch '^\.' -and $_.Name -notmatch '^_' } | Sort-Object Name
 $skillNames = $skillDirs.Name
 $instructionFiles = Get-ChildItem $instructionsDir -Filter '*.instructions.md' -EA SilentlyContinue
 $promptFiles = Get-ChildItem $promptsDir -Filter '*.prompt.md' -EA SilentlyContinue
@@ -264,7 +264,7 @@ if (Test-Path $pluginJsonFile) {
                 $chain += $name
                 return $chain
             }
-            $skillNames = (Get-ChildItem $skillsDir -Directory).Name
+            $skillNames = (Get-ChildItem $skillsDir -Directory | Where-Object { $_.Name -notmatch '^\.' -and $_.Name -notmatch '^_' }).Name
             $promptStems = (Get-ChildItem (Join-Path $pluginDir 'prompts') -File -Filter '*.prompt.md' -ErrorAction SilentlyContinue) `
                 | ForEach-Object { $_.Name -replace '\.prompt\.md$','' }
             $instructionStems = (Get-ChildItem (Join-Path $pluginDir 'instructions') -File -Filter '*.instructions.md' -ErrorAction SilentlyContinue) `
@@ -1663,7 +1663,7 @@ process.stdout.write(JSON.stringify(out));
     }
 
     $skillsRoot = Join-Path $Root 'plugin/skills'
-    $skillDirs = Get-ChildItem -Path $skillsRoot -Directory | Where-Object { $_.Name -notin @('eval', 'self-check') }
+    $skillDirs = Get-ChildItem -Path $skillsRoot -Directory | Where-Object { $_.Name -notin @('eval', 'self-check') -and $_.Name -notmatch '^_' }
     foreach ($sd in $skillDirs) {
         $evalsFile = Join-Path $sd.FullName 'evals/evals.json'
         if (-not (Test-Path $evalsFile)) {
@@ -1778,6 +1778,228 @@ process.stdout.write(JSON.stringify(out));
     }
 }
 
+    # === D35.log — State/log.md format and presence (v5.1.0+) ===
+    # Validates that writer-touched State dirs have log.md and that entries match canonical format.
+    # Operates on .testtmp/ fixtures or real engagement roots.
+    $logFixtureDir = Join-Path $Root '.testtmp'
+    $logTestDirs = @()
+    if (Test-Path $logFixtureDir) {
+        $logTestDirs += Get-ChildItem -Path $logFixtureDir -Recurse -Directory -ErrorAction SilentlyContinue |
+            Where-Object { $_.Name -eq 'State' -and (Test-Path (Join-Path $_.FullName 'log.md')) }
+    }
+    # Also check real engagement roots if available
+    foreach ($engRoot in (Resolve-EngagementRoots -RepoRoot $Root)) {
+        Get-ChildItem -Path $engRoot -Directory -ErrorAction SilentlyContinue | ForEach-Object {
+            $stateDir = Join-Path $_.FullName 'State'
+            if (Test-Path $stateDir) { $logTestDirs += Get-Item $stateDir }
+        }
+    }
+
+    foreach ($sd in $logTestDirs) {
+        $logMd = Join-Path $sd.FullName 'log.md'
+
+        # D35.log-exists
+        if (-not (Test-Path $logMd)) {
+            Add-Finding 'D35.log-exists' 'State log' 'warning' "State directory '$($sd.FullName)' has no log.md" "Add log.md per log-format.instructions.md. Run build-state to auto-create it." $sd.FullName 0
+            continue
+        }
+
+        # D35.log-format — every ## [ heading matches canonical format
+        $logLines = Get-Content -Path $logMd -ErrorAction SilentlyContinue
+        $prevTs = $null
+        $formatOk = $true
+        $monotonicOk = $true
+        foreach ($line in $logLines) {
+            if ($line -match '^\#\#\s+\[') {
+                if ($line -notmatch '^\#\#\s+\[\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}\]\s+\S+\s+\|\s+.+$') {
+                    Add-Finding 'D35.log-format' 'State log' 'warning' "log.md heading does not match canonical format: $line" "Heading must be: ## [YYYY-MM-DD HH:MM] <op> | <title>. See log-format.instructions.md." $logMd 0
+                    $formatOk = $false
+                    break
+                }
+                # D35.log-monotonic — timestamps non-decreasing (newest first = decreasing)
+                if ($line -match '^\#\#\s+\[(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2})\]') {
+                    try {
+                        $ts = [datetime]::ParseExact($Matches[1], 'yyyy-MM-dd HH:mm', $null)
+                        if ($prevTs -and $ts -gt $prevTs) {
+                            Add-Finding 'D35.log-monotonic' 'State log' 'warning' "log.md timestamps not reverse-chronological: $($Matches[1]) appears after an earlier timestamp" "Entries should be prepended (newest first). Re-order or re-run build-state." $logMd 0
+                            $monotonicOk = $false
+                            break
+                        }
+                        $prevTs = $ts
+                    } catch {}
+                }
+            }
+        }
+    }
+
+    # === D36.contradictions — contradiction handling integrity (v5.1.0+) ===
+    # Validates callout syntax, review-queue freshness, and build-state non-fenced preservation.
+    $contradictionDirs = @()
+    if (Test-Path $logFixtureDir) {
+        $contradictionDirs += Get-ChildItem -Path $logFixtureDir -Recurse -Directory -ErrorAction SilentlyContinue |
+            Where-Object { $_.Name -eq 'State' }
+    }
+    foreach ($engRoot in (Resolve-EngagementRoots -RepoRoot $Root)) {
+        Get-ChildItem -Path $engRoot -Directory -ErrorAction SilentlyContinue | ForEach-Object {
+            $stateDir = Join-Path $_.FullName 'State'
+            if (Test-Path $stateDir) { $contradictionDirs += Get-Item $stateDir }
+        }
+    }
+
+    foreach ($sd in $contradictionDirs) {
+        $mdFiles = Get-ChildItem -Path $sd.FullName -Recurse -Filter '*.md' -ErrorAction SilentlyContinue
+
+        # D36.callout-syntax — every > [!warning] Contradicted callout has required structure
+        foreach ($mf in $mdFiles) {
+            $content = Get-Content -Raw $mf.FullName -ErrorAction SilentlyContinue
+            if (-not $content) { continue }
+            if ($content -match '>\s*\[!warning\]\s*Contradicted') {
+                # Must have 'by' clause and a following > [!info] block
+                if ($content -notmatch '>\s*\[!warning\]\s*Contradicted\s+by\s+') {
+                    Add-Finding 'D36.callout-syntax' 'Contradictions' 'warning' "Callout in $($mf.Name) missing 'by <source>' clause" "Format: > [!warning] Contradicted by <skill> run <date>. See living-wiki.instructions.md." $mf.FullName 0
+                }
+            }
+        }
+
+        # D36.review-queue-fresh — if _review-queue.md has open items, most recent log entry is within 30 days
+        $reviewQueue = Join-Path $sd.FullName '_review-queue.md'
+        if (Test-Path $reviewQueue) {
+            $rqContent = Get-Content -Raw $reviewQueue -ErrorAction SilentlyContinue
+            # Check if review-queue has data rows (not just header + separator)
+            $rqLines = ($rqContent -split '\r?\n') | Where-Object { $_ -match '^\|' -and $_ -notmatch '^\|\s*-' -and $_ -notmatch '^\|\s*Entity' }
+            if ($rqLines.Count -gt 0) {
+                # Has table rows (open items)
+                $logMd2 = Join-Path $sd.FullName 'log.md'
+                if (Test-Path $logMd2) {
+                    $logContent2 = Get-Content -Raw $logMd2
+                    $recentEntry = $false
+                    if ($logContent2 -match '(?m)^\#\#\s+\[(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2})\]') {
+                        try {
+                            $lastTs = [datetime]::ParseExact($Matches[1], 'yyyy-MM-dd HH:mm', $null)
+                            if (((Get-Date) - $lastTs).TotalDays -le 30) { $recentEntry = $true }
+                        } catch {}
+                    }
+                    if (-not $recentEntry) {
+                        Add-Finding 'D36.review-queue-fresh' 'Contradictions' 'warning' "_review-queue.md has open items but most recent log entry is >30 days old" "Run 'lint-state' or 'build-state' to refresh. Open contradictions need periodic review." $reviewQueue 0
+                    }
+                }
+            }
+        }
+
+        # D36.no-silent-overwrite — build-state preserves non-fenced regions
+        # This check validates the invariant by looking for the fencing pattern.
+        # If State pages exist with kushi:auto fences AND content outside fences,
+        # verify the file has not been fully regenerated (check mtime consistency).
+        # For the fixture-based test: run build-state twice, assert non-fenced bytes unchanged.
+        # In self-check, we do a structural check: if a page has content outside fences,
+        # verify it also has content INSIDE fences (indicating incremental mode is active).
+        foreach ($mf in $mdFiles) {
+            $content = Get-Content -Raw $mf.FullName -ErrorAction SilentlyContinue
+            if (-not $content) { continue }
+            if ($content -notmatch 'kushi_state_page:\s*true') { continue }
+            if ($content -match '<!-- kushi:auto:start') {
+                # Good — page uses fencing. Verify fence pairs are balanced.
+                $starts = ([regex]::Matches($content, '<!-- kushi:auto:start')).Count
+                $ends = ([regex]::Matches($content, '<!-- kushi:auto:end')).Count
+                if ($starts -ne $ends) {
+                    Add-Finding 'D36.no-silent-overwrite' 'Contradictions' 'warning' "$($mf.Name) has mismatched kushi:auto fence pairs ($starts starts, $ends ends)" "Every <!-- kushi:auto:start --> must have a matching <!-- kushi:auto:end -->. Fix the fencing." $mf.FullName 0
+                }
+            }
+        }
+    }
+
+    # === D37.hooks — Hooks system integrity (v5.2.0+) ===
+
+    # D37.hooks-doctrine-exists
+    $hooksDoctrine = Join-Path $instructionsDir 'hooks.instructions.md'
+    if (-not (Test-Path $hooksDoctrine)) {
+        Add-Finding 'D37.hooks-doctrine-exists' 'Hooks' 'warning' "hooks.instructions.md is missing" "Create plugin/instructions/hooks.instructions.md per v5.2.0 spec." $hooksDoctrine 0
+    }
+
+    # D37.hooks-helper-exists
+    $hooksHelper = Join-Path $skillsDir '_shared\Invoke-Hooks.ps1'
+    if (-not (Test-Path $hooksHelper)) {
+        Add-Finding 'D37.hooks-helper-exists' 'Hooks' 'warning' "Invoke-Hooks.ps1 shared helper is missing" "Create plugin/skills/_shared/Invoke-Hooks.ps1 per hooks.instructions.md." $hooksHelper 0
+    }
+
+    # D37.hooks-templates-exist
+    $templatesDir = Join-Path $skillsDir '_shared\hook-templates'
+    if (-not (Test-Path $templatesDir)) {
+        Add-Finding 'D37.hooks-templates-exist' 'Hooks' 'warning' "hook-templates/ directory is missing" "Create plugin/skills/_shared/hook-templates/ with at least teams-notify.ps1 and console-debug.ps1." $templatesDir 0
+    } else {
+        $templates = Get-ChildItem -Path $templatesDir -Filter '*.ps1' -ErrorAction SilentlyContinue
+        if ($templates.Count -lt 2) {
+            Add-Finding 'D37.hooks-templates-exist' 'Hooks' 'warning' "hook-templates/ has fewer than 2 templates (found $($templates.Count))" "Add teams-notify.ps1 and console-debug.ps1 templates." $templatesDir 0
+        }
+    }
+
+    # D37.hooks-log-format: if any fixture has a hooks-log.md, headings parse correctly
+    $hooksLogFixtures = @()
+    if (Test-Path $logFixtureDir) {
+        $hooksLogFixtures += Get-ChildItem -Path $logFixtureDir -Recurse -Filter 'hooks-log.md' -ErrorAction SilentlyContinue
+    }
+    foreach ($engRoot in (Resolve-EngagementRoots -RepoRoot $Root)) {
+        $hooksLogFixtures += Get-ChildItem -Path $engRoot -Recurse -Filter 'hooks-log.md' -ErrorAction SilentlyContinue
+    }
+    foreach ($hlf in $hooksLogFixtures) {
+        $hlContent = Get-Content -Path $hlf.FullName -ErrorAction SilentlyContinue
+        foreach ($line in $hlContent) {
+            if ($line -match '^\#\#\s+\[') {
+                if ($line -notmatch '^\#\#\s+\[\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}\]\s+\S+\s+\|\s+hook:\s+.+$') {
+                    Add-Finding 'D37.hooks-log-format' 'Hooks' 'warning' "hooks-log.md heading does not match canonical format: $line" "Heading must be: ## [YYYY-MM-DD HH:MM] <event> | hook: <name>. See hooks.instructions.md." $hlf.FullName 0
+                    break
+                }
+            }
+        }
+    }
+
+    # === D38.parallel — Parallel execution integrity (v5.2.0+) ===
+
+    # D38.parallel-doctrine-exists
+    $parallelDoctrine = Join-Path $instructionsDir 'parallel-execution.instructions.md'
+    if (-not (Test-Path $parallelDoctrine)) {
+        Add-Finding 'D38.parallel-doctrine-exists' 'Parallel' 'warning' "parallel-execution.instructions.md is missing" "Create plugin/instructions/parallel-execution.instructions.md per v5.2.0 spec." $parallelDoctrine 0
+    }
+
+    # D38.refresh-supports-parallel: grep for parallel/ThreadJob/workers in refresh-project
+    $refreshSkill = Join-Path $skillsDir 'refresh-project\SKILL.md'
+    if (Test-Path $refreshSkill) {
+        $refreshContent = Get-Content -Raw $refreshSkill
+        if ($refreshContent -notmatch 'parallel|ThreadJob|worker|concurrent' -and $refreshContent -notmatch 'parallel-execution\.instructions\.md') {
+            Add-Finding 'D38.refresh-supports-parallel' 'Parallel' 'warning' "refresh-project/SKILL.md does not reference parallel dispatch" "Add parallel dispatch documentation per parallel-execution.instructions.md." $refreshSkill 0
+        }
+    }
+
+    # D38.deterministic-order: verify parallel doctrine documents deterministic ordering
+    if (Test-Path $parallelDoctrine) {
+        $pdContent = Get-Content -Raw $parallelDoctrine
+        if ($pdContent -notmatch 'deterministic|canonical.*order') {
+            Add-Finding 'D38.deterministic-order' 'Parallel' 'warning' "parallel-execution doctrine does not document deterministic output ordering" "Add a section on deterministic ordering (canonical source order regardless of completion order)." $parallelDoctrine 0
+        }
+    }
+
+    # === D39.otel — OpenTelemetry export integrity (v5.2.0+) ===
+
+    # D39.otel-doctrine-exists
+    $otelDoctrine = Join-Path $instructionsDir 'otel.instructions.md'
+    if (-not (Test-Path $otelDoctrine)) {
+        Add-Finding 'D39.otel-doctrine-exists' 'OTel' 'warning' "otel.instructions.md is missing" "Create plugin/instructions/otel.instructions.md per v5.2.0 spec." $otelDoctrine 0
+    }
+
+    # D39.otel-helper-exists
+    $otelHelper = Join-Path $skillsDir '_shared\Emit-OtelSpan.ps1'
+    if (-not (Test-Path $otelHelper)) {
+        Add-Finding 'D39.otel-helper-exists' 'OTel' 'warning' "Emit-OtelSpan.ps1 shared helper is missing" "Create plugin/skills/_shared/Emit-OtelSpan.ps1 per otel.instructions.md." $otelHelper 0
+    }
+
+    # D39.otel-noop-when-unset: helper exits cleanly when KUSHI_OTEL_ENDPOINT is empty
+    if (Test-Path $otelHelper) {
+        $otelContent = Get-Content -Raw $otelHelper
+        if ($otelContent -notmatch 'KUSHI_OTEL_ENDPOINT.*return|return.*KUSHI_OTEL_ENDPOINT|\-not \$endpoint.*return') {
+            Add-Finding 'D39.otel-noop-when-unset' 'OTel' 'warning' "Emit-OtelSpan.ps1 does not appear to short-circuit when KUSHI_OTEL_ENDPOINT is unset" "Add early return when endpoint is empty: if (-not \$env:KUSHI_OTEL_ENDPOINT) { return }" $otelHelper 0
+        }
+    }
+
 # === Output ===
 if ($Targeted) {
     # Filter findings to those whose code, surface, file path, or message contain the substring.

package/plugin/skills/skill-checker/check-skill.ps1

@@ -88,7 +88,7 @@ function Get-TargetSkills {
         return @(Get-Item -LiteralPath $d)
     }
     if ($All) {
-        return Get-ChildItem -Path $skillsRoot -Directory | Where-Object { $excludeFromAll -notcontains $_.Name }
+        return Get-ChildItem -Path $skillsRoot -Directory | Where-Object { $excludeFromAll -notcontains $_.Name -and $_.Name -notmatch '^_' }
     }
     throw "Specify -Skill <name> or -All."
 }

package/plugin/skills/teach/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: "teach"
+version: "1.0.0"
+description: "USE WHEN the user asks 'explain how kushi does X', 'why does refresh do Y', 'what is the difference between A and B in kushi', 'kushi explain <topic>', or wants to understand a kushi concept. DO NOT USE for modifying state/evidence (use build-state/refresh) or for project Q&A (use ask-project). Capability: pure pedagogical output — loads relevant doctrine + genealogy, explains concepts with cross-references, never modifies any State or Evidence."
+---
+
+# Skill: teach
+
+Pure pedagogical skill. Explains kushi concepts, architecture decisions, and operational patterns by loading relevant doctrine snippets, cross-references, and genealogy entries.
+
+## Triggers
+
+- "explain how kushi does X"
+- "why does refresh do Y"
+- "what's the difference between A and B in kushi"
+- `kushi explain <topic>` (CLI verb)
+- "how does kushi handle contradictions?"
+- "teach me about the CSC format"
+
+## Inputs
+
+- `<topic>` — free-text topic (fuzzy-matched to doctrine clusters below).
+
+## Topic → Doctrine mapping
+
+| Topic keyword(s) | Primary doctrine | Supporting files |
+|------------------|-----------------|-----------------|
+| contradictions, conflicts | `living-wiki.instructions.md` | `wiki-lint.instructions.md`, `State/_review-queue.md` format |
+| refresh, pull, sources | `refresh-project/SKILL.md` | `verbatim-by-default.instructions.md`, `parallel-execution.instructions.md` |
+| state, build-state, wiki | `living-wiki.instructions.md` | `karpathy-state-layout.instructions.md`, `log-format.instructions.md` |
+| hooks, events, webhooks | `hooks.instructions.md` | `Invoke-Hooks.ps1` |
+| parallel, workers, speed | `parallel-execution.instructions.md` | `auth-and-retry.instructions.md` |
+| otel, telemetry, tracing | `otel.instructions.md` | `Emit-OtelSpan.ps1` |
+| csc, capture, weekly | `comprehensive-structured-capture.instructions.md` | `weekly-csc.instructions.md` |
+| graph, entities, links | `entity-graph.instructions.md` | `link-entities/SKILL.md` |
+| workiq, m365 | `workiq-only.instructions.md` | `workiq-input-sanitization.instructions.md` |
+| schema, conventions, remember | `schema-evolve.instructions.md` | `karpathy-state-layout.instructions.md` |
+| install, setup, hosts | `multi-host-install.instructions.md` | `host-portability.instructions.md` |
+| evals, testing | `skill-evals.instructions.md` | `skill-authoring.instructions.md` |
+
+## Procedure
+
+1. **Match topic** — fuzzy-match user's topic to doctrine cluster. If no match, list available topics with one-line descriptions.
+2. **Load doctrine** — read the primary doctrine file + first 20 lines of each supporting file.
+3. **Load genealogy** — find the release that introduced the feature in `docs/genealogy.md`.
+4. **Explain** — synthesize a clear explanation with:
+   - What it does (2-3 sentences)
+   - Why it exists (the problem it solved — from genealogy)
+   - How it works (key mechanics from doctrine)
+   - Where to look (file paths)
+   - Related concepts (cross-references)
+5. **Never modify** — this skill is read-only. No writes to State/, Evidence/, or any file.
+
+## Gotchas
+
+1. **Topic not found**: List available topics with `kushi explain --list`. Don't guess.
+2. **Too broad**: If topic matches multiple clusters, ask user to narrow down.
+3. **Version-specific**: Always note which version introduced the feature.
+4. **No project context needed**: teach operates on the kushi repo itself, not on engagement evidence.
+5. **Doctrine drift**: Always read the file live — don't cache doctrine content.
+
+## Validation loop
+
+After generating explanation:
+1. Verify all cited file paths exist (glob check).
+2. Verify genealogy entry referenced is real.
+3. If a path doesn't exist, remove the citation rather than citing a phantom file.
+
+## References
+
+- `release-genealogy.instructions.md` — genealogy format
+- `skill-authoring.instructions.md` — skill structure conventions
+- `docs/genealogy.md` — release lineage
+
+## Issue Recovery
+
+When this skill exposes a reusable defect (doctrine gap, missing cross-reference, stale genealogy), 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/teach/evals/evals.json

@@ -0,0 +1,37 @@
+{
+  "skill": "teach",
+  "cases": [
+    {
+      "id": "teach-contradictions",
+      "name": "Explain contradictions handling",
+      "input": "kushi explain contradictions",
+      "expected_assertions": [
+        { "type": "contains", "value": "living-wiki" },
+        { "type": "contains", "value": "callout" },
+        { "type": "contains", "value": "_review-queue" }
+      ],
+      "grader_type": "script"
+    },
+    {
+      "id": "teach-parallel",
+      "name": "Explain parallel refresh",
+      "input": "explain how parallel pulls work in kushi",
+      "expected_assertions": [
+        { "type": "contains", "value": "parallel" },
+        { "type": "contains", "value": "worker" },
+        { "type": "contains", "value": "max_workers" }
+      ],
+      "grader_type": "script"
+    },
+    {
+      "id": "teach-unknown-topic",
+      "name": "Unknown topic suggests alternatives",
+      "input": "kushi explain quantum-entanglement",
+      "expected_assertions": [
+        { "type": "not_contains", "value": "quantum" },
+        { "type": "contains", "value": "available" }
+      ],
+      "grader_type": "script"
+    }
+  ]
+}

package/plugin/templates/state/answers.README.md

@@ -0,0 +1,7 @@
+# State/answers/
+
+This folder contains filed-back Q&A answers from `ask-project --file-back`.
+
+Each file is named `YYYY-MM-DD_<slug>.md` and contains the question, answer, and source citations.
+
+These are durable knowledge artifacts — they persist across refreshes and serve as a queryable FAQ for the project.

package/plugin/templates/state/hot.template.md

@@ -0,0 +1,12 @@
+---
+kushi_state_hot: true
+generated_at: "{{generated_at}}"
+---
+
+# Hot — {{project}}
+
+> _Auto-generated. Entities touched in the last 7 days, ranked by recency. Content between fences is regenerated on every build-state run._
+
+<!-- kushi:auto:start section="hot-entities" -->
+{{hot_entities}}
+<!-- kushi:auto:end section="hot-entities" -->

package/plugin/templates/state/review-queue.template.md

@@ -0,0 +1,10 @@
+---
+kushi_state_review_queue: true
+---
+
+# Review Queue
+
+> _Open contradictions requiring human review. Updated by build-state when contradictions are detected. Cleared when resolved (auto or manual)._
+
+| Entity | Property | Old value | New value | Flagged | Sources |
+|---|---|---|---|---|---|

package/src/eval-runner.test.mjs

@@ -35,7 +35,7 @@ test('eval-runner: evals.schema.json validates structurally', () => {
 test('eval-runner: every plugin/skills/<name>/ (except eval/) has evals/evals.json that parses', () => {
   const skillsDir = path.join(repoRoot, 'plugin/skills');
   const skills = fs.readdirSync(skillsDir, { withFileTypes: true })
-    .filter((d) => d.isDirectory() && d.name !== 'eval')
+    .filter((d) => d.isDirectory() && d.name !== 'eval' && !d.name.startsWith('_'))
     .map((d) => d.name);
   const missing = [];
   for (const skill of skills) {

package/src/hooks-dispatcher.test.mjs

@@ -0,0 +1,135 @@
+// kushi v5.2.0 — hooks dispatcher tests.
+// Validates Invoke-Hooks.ps1 behavior: ordering, failure isolation, payload format.
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const invokeHooks = path.join(repoRoot, 'plugin', 'skills', '_shared', 'Invoke-Hooks.ps1');
+
+function setupFixture(label) {
+  const root = path.resolve(repoRoot, '.testtmp', `hooks-${label}-${Date.now()}`);
+  const hooksDir = path.join(root, '.kushi', 'hooks');
+  const stateDir = path.join(root, 'Evidence', 'tester', 'State');
+  fs.mkdirSync(hooksDir, { recursive: true });
+  fs.mkdirSync(stateDir, { recursive: true });
+  return { root, hooksDir, stateDir };
+}
+
+function cleanup(root) {
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+test('hooks: scripts invoked in declaration order', () => {
+  const { root, hooksDir, stateDir } = setupFixture('order');
+  try {
+    // Create two hook scripts that write to a shared file
+    const orderFile = path.join(root, 'order.txt');
+    const hook1 = path.join(hooksDir, 'first.ps1');
+    const hook2 = path.join(hooksDir, 'second.ps1');
+    // Use simple scripts that write via Out-File
+    fs.writeFileSync(hook1, `$input | Out-Null\n'first' | Out-File -Append -FilePath '${orderFile.replace(/\\/g, '/')}' -Encoding utf8`);
+    fs.writeFileSync(hook2, `$input | Out-Null\n'second' | Out-File -Append -FilePath '${orderFile.replace(/\\/g, '/')}' -Encoding utf8`);
+
+    // Create hooks.yml referencing both in order
+    const hooksYml = path.join(root, '.kushi', 'hooks.yml');
+    fs.writeFileSync(hooksYml, [
+      'hooks:',
+      '  post-pull:',
+      '    - type: script',
+      '      path: .kushi/hooks/first.ps1',
+      '    - type: script',
+      '      path: .kushi/hooks/second.ps1',
+    ].join('\n'));
+
+    const script = `& '${invokeHooks.replace(/\\/g, '/')}' -ProjectRoot '${root.replace(/\\/g, '/')}' -Event 'post-pull' -Payload @{ project = 'test'; source = 'email'; success = $true } -StateDir '${stateDir.replace(/\\/g, '/')}'`;
+    const r = spawnSync('pwsh', ['-NoProfile', '-Command', script], { encoding: 'utf8', timeout: 15000 });
+
+    // The helper should not crash
+    assert.equal(r.status, 0, `invoke-hooks should exit 0: stderr=${r.stderr?.substring(0, 200)}`);
+
+    // Check hooks-log.md was written
+    const logFile = path.join(stateDir, 'hooks-log.md');
+    assert.ok(fs.existsSync(logFile), `hooks-log.md should be created. stdout: ${r.stdout?.substring(0,200)}`);
+    const logContent = fs.readFileSync(logFile, 'utf8');
+    assert.match(logContent, /post-pull/, 'log should mention the event');
+  } finally {
+    cleanup(root);
+  }
+});
+
+test('hooks: failure of one hook does not block others', () => {
+  const { root, hooksDir, stateDir } = setupFixture('failiso');
+  try {
+    // First hook throws, second should still run
+    const successFile = path.join(root, 'success.txt');
+    const hook1 = path.join(hooksDir, 'post-pull.ps1');
+    fs.writeFileSync(hook1, `throw "deliberate failure"`);
+
+    const hook2Path = path.join(hooksDir, 'ok.ps1');
+    fs.writeFileSync(hook2Path, `$input | Out-Null\n'ran' | Out-File -FilePath '${successFile.replace(/\\/g, '/')}' -Encoding utf8`);
+
+    const hooksYml = path.join(root, '.kushi', 'hooks.yml');
+    fs.writeFileSync(hooksYml, [
+      'hooks:',
+      '  post-pull:',
+      '    - type: script',
+      '      path: .kushi/hooks/post-pull.ps1',
+      '    - type: script',
+      '      path: .kushi/hooks/ok.ps1',
+    ].join('\n'));
+
+    const script = `& '${invokeHooks.replace(/\\/g, '/')}' -ProjectRoot '${root.replace(/\\/g, '/')}' -Event 'post-pull' -Payload @{ project = 'test'; source = 'email'; success = $true } -StateDir '${stateDir.replace(/\\/g, '/')}'`;
+    const r = spawnSync('pwsh', ['-NoProfile', '-Command', script], { encoding: 'utf8', timeout: 15000 });
+
+    // The process should NOT have crashed (exit 0)
+    assert.equal(r.status, 0, `hook dispatcher should not crash: ${r.stderr?.substring(0,200)}`);
+    // Second hook should have run
+    assert.ok(fs.existsSync(successFile), `second hook should still run after first fails. stdout=${r.stdout?.substring(0,200)}`);
+  } finally {
+    cleanup(root);
+  }
+});
+
+test('hooks: webhook payload has correct JSON structure', () => {
+  // We can't test real webhooks, but we can verify the payload format
+  // by checking the Invoke-Hooks.ps1 script constructs proper JSON
+  const content = fs.readFileSync(invokeHooks, 'utf8');
+  // Verify it converts payload to JSON
+  assert.match(content, /ConvertTo-Json/, 'must serialize payload to JSON');
+  // Verify it uses Invoke-RestMethod for webhooks
+  assert.match(content, /Invoke-RestMethod/, 'must use Invoke-RestMethod for webhooks');
+  // Verify Content-Type header
+  assert.match(content, /application\/json/, 'must set JSON content type');
+  // Verify timeout
+  assert.match(content, /TimeoutSec/, 'must set a timeout for webhooks');
+});
+
+test('hooks: hooks-log.md format has correct heading structure', () => {
+  const { root, hooksDir, stateDir } = setupFixture('logfmt');
+  try {
+    const hook = path.join(hooksDir, 'post-pull.ps1');
+    fs.writeFileSync(hook, `$input | Out-Null; Write-Output 'ok'`);
+
+    const script = `
+      $payload = @{ project = 'Acme'; source = 'teams'; success = $true; duration_ms = 150 }
+      & '${invokeHooks.replace(/\\/g, '\\\\')}' -ProjectRoot '${root.replace(/\\/g, '\\\\')}' -Event 'post-pull' -Payload $payload -StateDir '${stateDir.replace(/\\/g, '\\\\')}'
+    `;
+    spawnSync('pwsh', ['-NoProfile', '-Command', script], { encoding: 'utf8' });
+
+    const logFile = path.join(stateDir, 'hooks-log.md');
+    if (fs.existsSync(logFile)) {
+      const content = fs.readFileSync(logFile, 'utf8');
+      // Check heading format matches: ## [YYYY-MM-DD HH:MM] <event> | hook: <name>
+      assert.match(content, /## \[\d{4}-\d{2}-\d{2} \d{2}:\d{2}\] post-pull \| hook:/, 'heading format must be canonical');
+      assert.match(content, /- status:/, 'must include status field');
+      assert.match(content, /- duration_ms:/, 'must include duration field');
+    }
+  } finally {
+    cleanup(root);
+  }
+});

package/src/otel-emit.test.mjs

@@ -0,0 +1,73 @@
+// kushi v5.2.0 — OTel emit tests.
+// Validates no-op behavior, OTLP payload format, and privacy contract.
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const emitOtel = path.join(repoRoot, 'plugin', 'skills', '_shared', 'Emit-OtelSpan.ps1');
+
+test('otel: no-op when KUSHI_OTEL_ENDPOINT is unset', () => {
+  // Run the helper with no endpoint — should exit cleanly with no output
+  const script = `
+    $env:KUSHI_OTEL_ENDPOINT = ''
+    & '${emitOtel.replace(/\\/g, '\\\\')}' -SpanName 'kushi.pull' -Attributes @{ project='test'; success=$true }
+    Write-Output 'DONE'
+  `;
+  const r = spawnSync('pwsh', ['-NoProfile', '-Command', script], {
+    encoding: 'utf8',
+    env: { ...process.env, KUSHI_OTEL_ENDPOINT: '' }
+  });
+  assert.equal(r.status, 0, `should exit cleanly: ${r.stderr}`);
+  assert.match(r.stdout, /DONE/, 'script should complete without error');
+  // Should NOT contain any HTTP-related output
+  assert.ok(!r.stdout.includes('Invoke-RestMethod'), 'should not attempt HTTP when unset');
+});
+
+test('otel: helper script has correct OTLP payload structure', () => {
+  const content = fs.readFileSync(emitOtel, 'utf8');
+  // Verify OTLP JSON structure elements
+  assert.match(content, /resourceSpans/, 'must build resourceSpans');
+  assert.match(content, /scopeSpans/, 'must build scopeSpans');
+  assert.match(content, /traceId/, 'must include traceId');
+  assert.match(content, /spanId/, 'must include spanId');
+  assert.match(content, /startTimeUnixNano/, 'must include start time in nanos');
+  assert.match(content, /endTimeUnixNano/, 'must include end time in nanos');
+  assert.match(content, /service\.name.*kushi/, 'service.name must be kushi');
+});
+
+test('otel: privacy — only allowed attribute keys pass through', () => {
+  const content = fs.readFileSync(emitOtel, 'utf8');
+  // Verify allowlist exists
+  assert.match(content, /allowedKeys/, 'must have an allowedKeys filter');
+  // Verify common safe keys are in the list
+  assert.match(content, /'project'/, 'project must be allowed');
+  assert.match(content, /'source'/, 'source must be allowed');
+  assert.match(content, /'success'/, 'success must be allowed');
+  // Verify filtering logic — keys not in allowed are skipped
+  assert.match(content, /\-notin \$allowedKeys/, 'must skip keys not in allowlist');
+});
+
+test('otel: emits correct span kind (INTERNAL)', () => {
+  const content = fs.readFileSync(emitOtel, 'utf8');
+  // SPAN_KIND_INTERNAL = 1
+  assert.match(content, /kind\s*=\s*1/, 'span kind must be INTERNAL (1)');
+});
+
+test('otel: handles missing endpoint gracefully without errors', () => {
+  // Run with explicitly empty endpoint
+  const script = `
+    Remove-Item Env:KUSHI_OTEL_ENDPOINT -ErrorAction SilentlyContinue
+    & '${emitOtel.replace(/\\/g, '\\\\')}' -SpanName 'kushi.lint' -Attributes @{ findings_count=5 }
+    exit $LASTEXITCODE
+  `;
+  const r = spawnSync('pwsh', ['-NoProfile', '-Command', script], {
+    encoding: 'utf8',
+    env: { ...process.env, KUSHI_OTEL_ENDPOINT: undefined }
+  });
+  assert.equal(r.status, 0, 'must not fail when endpoint is missing');
+});