kushi-agents 5.0.4 → 5.2.0

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/Update-StateIndex.ps1

@@ -0,0 +1,47 @@
+<#
+.SYNOPSIS
+Updates the "Last touched" pointer at the top of State/index.md per log-format.instructions.md.
+
+.DESCRIPTION
+Idempotent helper. Updates or inserts the "Last touched" line immediately after
+the front-matter block in index.md.
+
+.PARAMETER StateDir
+Path to the State/ directory.
+
+.PARAMETER Op
+Operation name (same taxonomy as Append-StateLog).
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)][string]$StateDir,
+    [Parameter(Mandatory)][string]$Op
+)
+
+$ErrorActionPreference = 'Stop'
+
+$indexFile = Join-Path $StateDir 'index.md'
+$timestamp = Get-Date -Format 'yyyy-MM-dd HH:mm'
+$pointer = "> Last touched: $timestamp by $Op ([log](log.md))"
+
+if (-not (Test-Path $indexFile)) {
+    Write-Warning "index.md not found at $indexFile — skipping Update-StateIndex."
+    return
+}
+
+$content = Get-Content -Raw $indexFile
+$pointerPattern = '(?m)^> Last touched:.*$'
+
+if ($content -match $pointerPattern) {
+    $content = $content -replace $pointerPattern, $pointer
+} else {
+    # Insert after front-matter closing ---
+    if ($content -match '(?ms)(^---\r?\n.*?\r?\n---\r?\n)(.*)$') {
+        $content = $Matches[1] + "`n" + $pointer + "`n" + $Matches[2]
+    } else {
+        $content = $pointer + "`n`n" + $content
+    }
+}
+
+Set-Content -Path $indexFile -Value $content -Encoding utf8NoBOM
+Write-Verbose "Updated index.md: Last touched $timestamp by $Op"

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

@@ -42,6 +42,36 @@ The user does NOT need to type `/ask-project` or `@Kushi ask`. If the message:
 - **Freshness gate, not freshness auto-fix.** If the freshest source relevant to the question is older than `chat.freshness_warn_days` (default 14), warn the user and offer `@Kushi refresh <project>` — but NEVER auto-refresh.
 - **Reference packs may be consulted for domain doctrine.** When the question maps to a known reference-pack domain (currently only `fde/` — FDE stages, fitness, CRM status meanings, intake gates, risk categories, "MACC", "is this FDE-fit"), ALSO load the matching reference pack as additional grounding using the 3-layer override order (project → user → packaged). Cite reference-pack assertions with `[source: reference-packs/<pack>/<file>.md · <layer>]` where layer is `packaged` / `user-override` / `project-override`. Reference-pack content NEVER overrides project Evidence/ for facts about *this* project; it only provides definitions, gates, and rubrics.
 
+## --file-back option (v5.1.0+)
+
+When the user passes `--file-back` (or says "file this answer back", "save this answer"):
+
+1. After answering normally, write the Q+A to `Evidence/<alias>/State/answers/YYYY-MM-DD_<slug>.md`:
+   ```markdown
+   ---
+   question: "<the user's original question>"
+   asked_at: <ISO-8601 timestamp>
+   sources: [<list of cited source paths>]
+   ---
+
+   ## Answer
+
+   <the answer text, with citations preserved>
+
+   ## Sources
+
+   - <source 1>
+   - <source 2>
+   ```
+2. The `<slug>` is derived from the question: lowercase, alphanumeric + hyphens, ≤ 60 chars.
+3. Append `ask-fileback` entry to `State/log.md` via `Append-StateLog.ps1`:
+   - Title: `Filed answer: <slug>`
+   - Summary: one-line description of the question.
+4. Update `State/index.md` via `Update-StateIndex.ps1 -Op ask-fileback`.
+5. If `State/answers/` does not exist, create it.
+
+The `--file-back` flag is OPTIONAL. Without it, ask-project behaves exactly as before (read-only, no writes).
+
 ## Inputs
 
 - `<project>` — fuzzy-matched project name. If multiple plausible matches, ask the user.

package/plugin/skills/build-state/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "build-state"
-version: "4.0.0"
+version: "5.0.0"
 description: "USE WHEN the user says \"regenerate State for <X>\", \"rebuild State\", or \"@Kushi state <X>\" AND the project already has Evidence/ populated. DO NOT USE to pull new evidence (use refresh-project or pull-*). Capability: pure re-render — reads Evidence/_index/entities.yml + weekly CSC + legacy fallback, writes <project>/State/ in BOTH legacy 00–09 synthesis (full profile) AND Karpathy layout (index.md + log.md + per-entity pages + CLAUDE.md/AGENTS.md). Plan-validate-execute writer."
 ---
 
@@ -56,7 +56,23 @@ runs — transient working artifact, not authoritative truth.
 
 ## Steps
 
-
+
+## v5.1.0 — Incremental mode (HARD RULE; per `living-wiki.instructions.md`)
+
+Build-state is now incremental by default:
+
+1. **Read existing State/ pages.** Before regenerating, load every existing `State/**/*.md`.
+2. **Preserve human edits.** Content OUTSIDE `<!-- kushi:auto:start -->` / `<!-- kushi:auto:end -->` fences is NEVER modified.
+3. **Re-derive fenced regions only.** For each `<!-- kushi:auto:start section="<id>" -->` block, re-derive content from current evidence and replace the block contents.
+4. **Contradiction detection.** When a re-derived fact contradicts an existing fact (different value for same entity property):
+   - Wrap both in `> [!warning] Contradicted` / `> [!info] New value` callouts per `living-wiki.instructions.md`.
+   - Add entity to `_review-queue.md`.
+5. **Auto-resolve.** Apply the auto-resolve threshold from `living-wiki.instructions.md` (≥3 sources + ≥30 days old + no human override).
+6. **Log + index.** Append `build-state` entry to `State/log.md` via `Append-StateLog.ps1`. Update `State/index.md` via `Update-StateIndex.ps1`.
+
+When creating NEW pages (entity not previously in State/), wrap all auto-derived content in `<!-- kushi:auto -->` fences.
+
+
 ## Step checklist
 
 Progress-trackable view of the steps below. Each `### Step` block expands the corresponding checkbox.

package/plugin/skills/lint-state/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: "lint-state"
+version: "1.0.0"
+description: "USE WHEN the user says 'lint state', 'check state health', 'wiki lint', 'kushi lint <project>', or 'find stale/orphan/contradictions in State'. DO NOT USE for evidence-level validation (use self-check) or for rebuilding State (use build-state). Capability: runs wiki-lint finding classes against Evidence/<alias>/State/, writes dated lint report, updates log.md + index.md."
+---
+
+# Skill: lint-state
+
+Run wiki-lint checks against a project's `State/` directory per `wiki-lint.instructions.md`. Reports contradictions, stale claims, orphan pages, missing cross-refs, and data gaps — each with a ready-to-paste fix snippet.
+
+## Triggers
+
+- "lint state for `<project>`"
+- "check state health"
+- "wiki lint `<project>`"
+- `kushi lint <project>` (CLI verb)
+- "find contradictions in State"
+- "any stale claims in `<project>`?"
+
+## Inputs
+
+- `<project>` — engagement name (fuzzy-matched per `engagement-root-resolution.instructions.md`).
+
+## Step checklist
+
+- [ ] Step 1 — Resolve project root + State/ path
+- [ ] Step 2 — Run finding-class checks
+- [ ] Step 3 — Generate lint report
+- [ ] Step 4 — Update log.md + index.md
+- [ ] Step 5 — Print summary
+
+### Step 1 — Resolve project root
+
+Resolve `<engagement-root>/<project>/Evidence/<alias>/State/` using standard engagement-root resolution. Verify `State/` exists; if not, advise running `build-state` first.
+
+### Step 2 — Run finding-class checks
+
+Per `wiki-lint.instructions.md`, execute each finding class:
+
+1. **contradiction-flagged**: scan `State/**/*.md` for `> [!warning] Contradicted` callouts.
+2. **stale-claim**: parse citations, flag entities with newest citation > 60 days old.
+3. **orphan-page**: find pages with `kushi_state_page: true` not linked from index.md or siblings.
+4. **missing-cross-ref**: cross-reference entity mentions against frontmatter `entity_ids`/`related`.
+5. **data-gap**: find section headers with empty/placeholder bodies.
+
+### Step 3 — Generate lint report
+
+Write `Evidence/<alias>/State/reports/lint-YYYY-MM-DD.md`:
+
+```markdown
+---
+generated_at: "YYYY-MM-DDTHH:MM:SSZ"
+generated_by: "lint-state v1.0.0"
+findings_count: N
+---
+
+# Lint Report — YYYY-MM-DD
+
+## Summary
+
+| Class | Count | Severity |
+|---|---|---|
+| contradiction-flagged | N | warning |
+| stale-claim | N | warning |
+| orphan-page | N | warning |
+| missing-cross-ref | N | info |
+| data-gap | N | info |
+
+**Total findings: N**
+
+## Findings
+
+### contradiction-flagged: <entity> — <description>
+...per wiki-lint.instructions.md format...
+```
+
+### Step 4 — Update log.md + index.md
+
+Call shared helpers:
+- `Append-StateLog.ps1 -Op lint-state -Title "Lint pass (<N> findings)"`
+- `Update-StateIndex.ps1 -Op lint-state`
+
+### Step 5 — Print summary
+
+One-line console output: `lint-state: <N> findings (<breakdown by class>). Report: State/reports/lint-YYYY-MM-DD.md`
+
+## Validation loop
+
+After writing outputs:
+1. Verify `State/reports/lint-YYYY-MM-DD.md` exists and has valid frontmatter.
+2. Verify `State/log.md` has the new entry at top.
+3. Verify `State/index.md` "Last touched" pointer is updated.
+
+## References
+
+- `../../instructions/wiki-lint.instructions.md`
+- `../../instructions/log-format.instructions.md`
+- `../../instructions/living-wiki.instructions.md`

package/plugin/skills/lint-state/evals/evals.json

@@ -0,0 +1,34 @@
+{
+  "skill": "lint-state",
+  "version": "1.0.0",
+  "description": "Wiki-lint checks against State/ — contradictions, stale claims, orphans, cross-refs, data gaps.",
+  "cases": [
+    {
+      "id": "lint-state-clean",
+      "name": "Lint a clean State/ with no findings",
+      "input": "Run lint against a well-maintained State/ directory with no contradictions, stale claims, or orphans.",
+      "expected_assertions": [
+        { "type": "regex-match", "target": "stdout", "pattern": "lint-state: 0 findings" }
+      ],
+      "grader_type": "script"
+    },
+    {
+      "id": "lint-state-contradiction",
+      "name": "Lint detects contradiction callouts",
+      "input": "Run lint against a State/ directory with one unresolved > [!warning] Contradicted callout.",
+      "expected_assertions": [
+        { "type": "regex-match", "target": "stdout", "pattern": "contradiction-flagged=1" }
+      ],
+      "grader_type": "script"
+    },
+    {
+      "id": "lint-state-orphan",
+      "name": "Lint detects orphan pages",
+      "input": "Run lint against a State/ directory with a page that has kushi_state_page: true but is not linked from index.md.",
+      "expected_assertions": [
+        { "type": "regex-match", "target": "stdout", "pattern": "orphan-page=1" }
+      ],
+      "grader_type": "script"
+    }
+  ]
+}