kushi-agents 5.0.4 → 5.2.0

package/README.md

@@ -7,6 +7,10 @@
 [![host: VS Code](https://img.shields.io/badge/host-VS%20Code-007acc)](https://gim-home.github.io/kushi/)
 [![spec: agentskills.io](https://img.shields.io/badge/spec-agentskills.io-22c55e)](https://agentskills.io/skill-creation/best-practices)
 
+> **v5.2.0 — Hooks + parallel pulls + OTel + teach + schema-evolve.** Pipeline events trigger configurable hooks (`.kushi/hooks/`); pull dispatch is parallel by default (4 workers); OpenTelemetry export is opt-in via `KUSHI_OTEL_ENDPOINT`; `kushi explain <topic>` teaches concepts; `kushi remember <rule>` persists conventions.
+
+> **v5.1.0 — Living wiki.** Build-state is now incremental: human edits outside `<!-- kushi:auto -->` fences are preserved, contradictions are flagged with Obsidian-compatible callouts (`> [!warning]`), and a new `lint-state` skill monitors wiki health. State/ is a valid [Obsidian](https://obsidian.md) vault — callout syntax, Dataview-compatible frontmatter, and `[[wikilinks]]` all work natively.
+
 > **v5.0.1 spec-compliance pass.** Every `plugin/skills/<name>/SKILL.md` follows the [agentskills.io best practices](https://agentskills.io/skill-creation/best-practices) and [optimizing-descriptions](https://agentskills.io/skill-creation/optimizing-descriptions) guides: ≤ 500 lines & ≤ 5000 tokens, load-on-trigger references, top-5 gotchas, checklist orchestrators, validation loops, plan-validate-execute for graph + State writers, and "USE WHEN …" descriptions. Enforced by `self-check -Deep` D30.*.
 
 > **Project lineage:** for the *why* behind each release — what built on what, what trade-offs were accepted, what external work inspired which design — see [`docs/genealogy.md`](docs/genealogy.md). Every release MUST add an entry there before tagging (enforced by `self-check` D31.genealogy).
@@ -74,6 +78,80 @@ Apply [a]ll · [s]elect · [n]one?
 
 Try it: `npx kushi-agents --clawpilot --profile preview` · How-to: [Two-way ADO update](https://gim-home.github.io/kushi/how-to/two-way-ado-update/) · Roadmap: [`docs/concepts/roadmap.md`](docs/concepts/roadmap.md).
 
+## Obsidian compatible
+
+`State/` is a valid [Obsidian](https://obsidian.md) vault out of the box:
+
+- **Callout syntax** — contradictions use `> [!warning]` / `> [!info]` callouts (native Obsidian rendering).
+- **Dataview compatible** — every State page has YAML frontmatter (`kushi_state_page: true`, `entity_ids`, `related`, timestamps) queryable by [Dataview](https://blacksmithgu.github.io/obsidian-dataview/).
+- **Wikilinks** — cross-references use `[[category/slug]]` form, resolvable by Obsidian's link resolver.
+- **No binary assets required** — all content is plain Markdown. No images, no custom plugins needed.
+
+To use: point Obsidian at `<project>/State/` as a vault. The `index.md` serves as the home page, `log.md` is the activity feed, and category folders (`people/`, `decisions/`, etc.) are navigable in the sidebar.
+
+> **Note:** Obsidian is optional. State/ works identically without it — the conventions are designed to be tool-agnostic while being Obsidian-first for teams that use it.
+
+<!-- Screenshot placeholder: Obsidian rendering of State/ with contradiction callouts visible. No binary screenshots committed — use text descriptions or link to docs site. -->
+
+---
+
+## Hooks (v5.2.0+)
+
+Pipeline events (`post-pull`, `post-state`, `post-contradiction`, `post-lint`) trigger configurable hooks — PowerShell scripts or webhooks. Failures are logged but never block the pipeline.
+
+```bash
+# List configured hooks
+kushi hooks list MyProject
+
+# Test-fire a synthetic event
+kushi hooks test MyProject post-pull
+```
+
+Configure in `.kushi/hooks.yml` or drop scripts into `.kushi/hooks/<event>.ps1`. Templates at `plugin/skills/_shared/hook-templates/`.
+
+## Parallel refresh (v5.2.0+)
+
+Pull dispatch is parallel by default (4 workers). Each source writes to its own isolated subtree. Results are aggregated in canonical source order for deterministic output.
+
+```bash
+# Default: parallel (up to 4 workers)
+kushi refresh MyProject
+
+# Force sequential (old behavior)
+kushi refresh MyProject --sequential
+```
+
+Configure `parallel.max_workers` in `.kushi/config.yml`. See `parallel-execution.instructions.md`.
+
+## Telemetry (opt-in, v5.2.0+)
+
+Set `KUSHI_OTEL_ENDPOINT` to export spans to any OTLP-compatible backend (Jaeger, Grafana Tempo, Azure Monitor). Zero overhead when unset. No evidence content or PII — metadata only.
+
+```bash
+export KUSHI_OTEL_ENDPOINT=http://localhost:4318/v1/traces
+kushi refresh MyProject  # spans emitted for each pull + build-state + lint
+```
+
+## Teach mode (v5.2.0+)
+
+Pedagogical, read-only. Explains kushi concepts by loading relevant doctrine + genealogy.
+
+```bash
+kushi explain contradictions
+kushi explain parallel
+kushi explain hooks
+```
+
+## Schema evolve (v5.2.0+)
+
+Teach kushi project-specific conventions that persist across runs.
+
+```bash
+kushi remember "always use 'HCA' not 'Healthcare Accelerator' in summaries"
+```
+
+Rules stored in `Evidence/<alias>/State/CLAUDE.md`. Read by `build-state`, `ask-project`, `refresh-project` at run start.
+
 ---
 
 ## Three install profiles

package/bin/cli.mjs

@@ -15,6 +15,51 @@ if (args.length > 0 && SKILL_VERBS.has(args[0])) {
   process.exit(0);
 }
 
+// ── lint verb (v5.1.0+) ──────────────────────────────────────────────────────
+if (args.length > 0 && args[0] === 'lint') {
+  const project = args[1] || '';
+  if (!project) {
+    console.error('\n  Usage: kushi lint <project>\n');
+    process.exit(1);
+  }
+  await dispatchLint(project);
+  process.exit(0);
+}
+
+// ── hooks verb (v5.2.0+) ─────────────────────────────────────────────────────
+if (args.length > 0 && args[0] === 'hooks') {
+  const sub = args[1] || '';
+  const project = args[2] || '';
+  if (!sub || !project || !['list', 'test'].includes(sub)) {
+    console.error('\n  Usage: kushi hooks list <project>\n         kushi hooks test <project> <event>\n');
+    process.exit(1);
+  }
+  await dispatchHooks(sub, project, args.slice(3));
+  process.exit(0);
+}
+
+// ── explain verb (v5.2.0+) ───────────────────────────────────────────────────
+if (args.length > 0 && args[0] === 'explain') {
+  const topic = args.slice(1).join(' ');
+  if (!topic) {
+    console.error('\n  Usage: kushi explain <topic>\n\n  Available topics: contradictions, refresh, state, hooks, parallel, otel, csc, graph, workiq, schema, install, evals\n');
+    process.exit(1);
+  }
+  await dispatchExplain(topic);
+  process.exit(0);
+}
+
+// ── remember verb (v5.2.0+) ──────────────────────────────────────────────────
+if (args.length > 0 && args[0] === 'remember') {
+  const rule = args.slice(1).join(' ');
+  if (!rule) {
+    console.error('\n  Usage: kushi remember <rule>\n\n  Example: kushi remember "always use HCA not Healthcare Accelerator"\n');
+    process.exit(1);
+  }
+  await dispatchRemember(rule);
+  process.exit(0);
+}
+
 if (args.includes('--help') || args.includes('-h')) {
   console.log(`
   Usage: npx kushi-agents [options]
@@ -61,13 +106,23 @@ if (args.includes('--help') || args.includes('-h')) {
                          Rewrite a skill's description per the optimizer rules.
     review-evals <skill> Render an HTML side-by-side eval-review viewer.
 
+  Wiki maintenance (v5.1.0+):
+    lint <project>       Run wiki-lint checks on State/ (contradictions, stale claims, orphans).
+
+  Hooks & observability (v5.2.0+):
+    hooks list <project>           List configured hooks for a project.
+    hooks test <project> <event>   Fire a synthetic hook event for testing.
+    explain <topic>                Explain a kushi concept (pedagogical, read-only).
+    remember <rule>                Persist a project convention to CLAUDE.md.
+
   After install, talk to Kushi:
     bootstrap <project>     First-time setup
     refresh <project>       Incremental refresh + rebuild State/
     state <project>         Re-render State/ from existing Evidence
     consolidate <project>   Merge per-user evidence
     status <project>        Show run-log
-    ask <project> <q>       Cited Q&A over Evidence/ (auto-routes)
+    ask <project> <q>       Cited Q&A over Evidence/ (auto-routes, --file-back to save)
+    lint <project>          Run wiki-lint checks on State/
 
   In VS Code Chat the prefix is "@Kushi". In Clawpilot just say "kushi <verb>".
 `);
@@ -210,6 +265,53 @@ async function dispatchSkillVerb(verb, rest) {
   process.exit(result.status ?? 1);
 }
 
+async function dispatchLint(project) {
+  const { spawn } = await import('node:child_process');
+  const { resolve } = await import('node:path');
+  const { fileURLToPath } = await import('node:url');
+  const __dirname = fileURLToPath(new URL('.', import.meta.url));
+  const scriptPath = resolve(__dirname, '..', 'plugin', 'skills', 'lint-state', 'lint.ps1');
+
+  const cwd = process.cwd();
+  const { readdirSync, existsSync } = await import('node:fs');
+  let stateDir = '';
+
+  const evidenceDir = resolve(cwd, project, 'Evidence');
+  if (existsSync(evidenceDir)) {
+    const aliases = readdirSync(evidenceDir, { withFileTypes: true })
+      .filter(d => d.isDirectory() && !d.name.startsWith('_'));
+    for (const alias of aliases) {
+      const candidate = resolve(evidenceDir, alias.name, 'State');
+      if (existsSync(candidate)) { stateDir = candidate; break; }
+    }
+  }
+
+  if (!stateDir) {
+    const direct = resolve(cwd, project, 'State');
+    if (existsSync(direct)) { stateDir = direct; }
+  }
+
+  if (!stateDir) {
+    console.error(`\n  Could not find State/ directory for project '${project}'.`);
+    console.error(`  Looked in: ${evidenceDir}/*/State/ and ${resolve(cwd, project, 'State')}/`);
+    console.error(`  Run 'kushi state ${project}' first to build State/.\n`);
+    process.exit(1);
+  }
+
+  const child = spawn('pwsh', ['-NoProfile', '-File', scriptPath, '-StateDir', stateDir], {
+    stdio: 'inherit',
+    cwd: resolve(__dirname, '..'),
+  });
+
+  return new Promise((res, rej) => {
+    child.on('close', (code) => {
+      if (code !== 0) rej(new Error(`lint-state exited with code ${code}`));
+      else res();
+    });
+    child.on('error', rej);
+  });
+}
+
 function pickFlag(args, flag) {
   const idx = args.indexOf(flag);
   if (idx !== -1 && idx + 1 < args.length) return args[idx + 1];
@@ -217,3 +319,101 @@ function pickFlag(args, flag) {
   const m = args.find((a) => a.startsWith(prefix));
   return m ? m.slice(prefix.length) : undefined;
 }
+
+// ── v5.2.0 dispatch helpers ──────────────────────────────────────────────────
+
+async function dispatchHooks(sub, project, extra) {
+  const { spawn } = await import('node:child_process');
+  const { resolve } = await import('node:path');
+  const { fileURLToPath } = await import('node:url');
+  const __dirname = fileURLToPath(new URL('.', import.meta.url));
+  const invokeHooks = resolve(__dirname, '..', 'plugin', 'skills', '_shared', 'Invoke-Hooks.ps1');
+
+  if (sub === 'list') {
+    // List hooks from .kushi/hooks.yml
+    const { existsSync, readFileSync } = await import('node:fs');
+    const hooksYml = resolve(process.cwd(), project, '.kushi', 'hooks.yml');
+    if (!existsSync(hooksYml)) {
+      console.log(`\n  No hooks configured for '${project}'. Create ${hooksYml} to add hooks.\n`);
+      return;
+    }
+    console.log(`\n  Hooks for '${project}' (${hooksYml}):\n`);
+    console.log(readFileSync(hooksYml, 'utf8'));
+  } else if (sub === 'test') {
+    const event = extra[0] || 'post-pull';
+    const script = `
+      $payload = @{ project = '${project}'; source = 'test'; success = $true; duration_ms = 0; event = '${event}' }
+      & '${invokeHooks.replace(/\\/g, '\\\\')}' -ProjectRoot '${resolve(process.cwd(), project).replace(/\\/g, '\\\\')}' -Event '${event}' -Payload $payload
+    `;
+    const child = spawn('pwsh', ['-NoProfile', '-Command', script], { stdio: 'inherit' });
+    return new Promise((res, rej) => {
+      child.on('close', (code) => { if (code !== 0) rej(new Error(`hooks test exited ${code}`)); else res(); });
+      child.on('error', rej);
+    });
+  }
+}
+
+async function dispatchExplain(topic) {
+  const { resolve } = await import('node:path');
+  const { existsSync, readFileSync } = await import('node:fs');
+  const { fileURLToPath } = await import('node:url');
+  const __dirname = fileURLToPath(new URL('.', import.meta.url));
+  const repoRoot = resolve(__dirname, '..');
+  const instructionsDir = resolve(repoRoot, 'plugin', 'instructions');
+
+  const topicMap = {
+    contradictions: 'living-wiki.instructions.md',
+    conflicts: 'living-wiki.instructions.md',
+    refresh: 'parallel-execution.instructions.md',
+    pull: 'parallel-execution.instructions.md',
+    state: 'living-wiki.instructions.md',
+    'build-state': 'living-wiki.instructions.md',
+    wiki: 'living-wiki.instructions.md',
+    hooks: 'hooks.instructions.md',
+    events: 'hooks.instructions.md',
+    webhooks: 'hooks.instructions.md',
+    parallel: 'parallel-execution.instructions.md',
+    workers: 'parallel-execution.instructions.md',
+    otel: 'otel.instructions.md',
+    telemetry: 'otel.instructions.md',
+    tracing: 'otel.instructions.md',
+    csc: 'comprehensive-structured-capture.instructions.md',
+    capture: 'comprehensive-structured-capture.instructions.md',
+    graph: 'entity-graph.instructions.md',
+    entities: 'entity-graph.instructions.md',
+    workiq: 'workiq-only.instructions.md',
+    schema: 'schema-evolve.instructions.md',
+    conventions: 'schema-evolve.instructions.md',
+    remember: 'schema-evolve.instructions.md',
+    install: 'multi-host-install.instructions.md',
+    setup: 'multi-host-install.instructions.md',
+    evals: 'skill-evals.instructions.md',
+  };
+
+  const key = Object.keys(topicMap).find(k => topic.toLowerCase().includes(k));
+  if (!key) {
+    console.log(`\n  Topic not found: "${topic}"\n`);
+    console.log('  Available topics:', Object.keys(topicMap).filter((v, i, a) => a.indexOf(v) === i).join(', '));
+    console.log('');
+    return;
+  }
+
+  const docFile = resolve(instructionsDir, topicMap[key]);
+  if (!existsSync(docFile)) {
+    console.error(`  Doctrine file missing: ${topicMap[key]}`);
+    process.exit(1);
+  }
+
+  const content = readFileSync(docFile, 'utf8');
+  const lines = content.split('\n').slice(0, 40);
+  console.log(`\n  📖 Topic: ${key} → ${topicMap[key]}\n`);
+  console.log(lines.join('\n'));
+  console.log(`\n  ... (full doctrine at: plugin/instructions/${topicMap[key]})\n`);
+}
+
+async function dispatchRemember(rule) {
+  console.log(`\n  ✅ Rule noted: "${rule}"`);
+  console.log('  To persist this rule, run schema-evolve from within a project context:');
+  console.log('    @Kushi remember ' + rule);
+  console.log('  This will write to Evidence/<alias>/State/CLAUDE.md\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "5.0.4",
+  "version": "5.2.0",
   "description": "Install Kushi — multi-source project evidence agent with Comprehensive Structured Capture (CSC) into weekly-only files across Email, Teams, OneNote, Loop, SharePoint, Meetings, CRM, ADO. Meetings retain a sibling verbatim/ audit folder. WorkIQ-only for M365 sources (Graph / m365_* FORBIDDEN as fallbacks; user-paste is first-class). Host-agnostic.",
   "type": "module",
   "bin": {
@@ -41,7 +41,7 @@
   },
   "license": "MIT",
   "scripts": {
-    "test": "node --test src/check-workiq.test.mjs src/seed-config.test.mjs src/sanitize-workiq-input.test.mjs src/detect-vertex-repo.test.mjs src/vertex-validate.test.mjs src/emit-vertex.e2e.test.mjs src/config-root-resolve.test.mjs src/forbidden-workiq-phrasings.test.mjs src/multi-host-install.test.mjs src/eval-aggregator.test.mjs src/eval-runner.test.mjs src/skill-creator.test.mjs src/skill-checker.test.mjs",
+    "test": "node --test src/check-workiq.test.mjs src/seed-config.test.mjs src/sanitize-workiq-input.test.mjs src/detect-vertex-repo.test.mjs src/vertex-validate.test.mjs src/emit-vertex.e2e.test.mjs src/config-root-resolve.test.mjs src/forbidden-workiq-phrasings.test.mjs src/multi-host-install.test.mjs src/eval-aggregator.test.mjs src/eval-runner.test.mjs src/skill-creator.test.mjs src/skill-checker.test.mjs src/hooks-dispatcher.test.mjs src/parallel-refresh.test.mjs src/otel-emit.test.mjs src/teach.test.mjs src/schema-evolve.test.mjs",
     "test:integration:bootstrap": "node src/bootstrap-dryrun.integration.test.mjs",
     "smoke": "node scripts/smoke.mjs",
     "eval": "pwsh plugin/skills/eval/run-evals.ps1 -Skill",

package/plugin/agents/kushi.agent.md

@@ -17,8 +17,8 @@ Kushi ships in three profiles. The installed profile is recorded in `kushi-insta
 | Profile | What's installed | Verbs available |
 |---|---|---|
 | `core` | Aggregator only: `setup`, `pull-*`, `consolidate-evidence`, `aggregate-project`, `ask-project`, `project-status`, `vertex-link`, `emit-vertex`, `self-check`, `eval`, `intro` | `setup`, `aggregate`, `consolidate`, `status`, `pull`, `ask`, `vertex-link`, `emit-vertex` |
-| `standard` *(default)* | core + `bootstrap-project`, `refresh-project`, `fde-intake`, `fde-report`, `fde-triage` + FDE reference pack | core + `bootstrap`, `refresh`, `fde-intake`, `fde-report`, `fde-triage` |
-| `full` | standard + `build-state` | standard + `state` |
+| `standard` *(default)* | core + `bootstrap-project`, `refresh-project`, `lint-state`, `fde-intake`, `fde-report`, `fde-triage` + FDE reference pack | core + `bootstrap`, `refresh`, `lint`, `fde-intake`, `fde-report`, `fde-triage` |
+| `full` | standard + `build-state`, `link-entities`, `dashboard`, `tour` | standard + `state`, `link-entities`, `dashboard`, `tour` |
 | **`preview`** *(opt-in)* | standard + `propose-ado-update`, `apply-ado-update` | standard + `propose-ado`, `apply-ado` |
 
 The Evidence/ folder produced by `aggregate` is the **public contract** between Kushi and any downstream consumer (external rollup repo, BI tooling). See `docs/reference/evidence-contract.md`.
@@ -39,6 +39,7 @@ The Evidence/ folder produced by `aggregate` is the **public contract** between
 | `@Kushi link-entities <project>` | standard+ | n/a (read-only) | v5.0.0 — `link-entities` writes `<project>/Evidence/_graph/project-graph.json` from per-source `_index/entities.yml` + weekly CSC bodies. Deterministic by default; opt-in LLM augment via `m365Mutable.graph.llm_infer`. |
 | `@Kushi dashboard <project>` | standard+ | n/a (read-only) | v5.0.0 — `dashboard` writes `<project>/dashboard.html` (single self-contained file). Cytoscape.js v3 + Clawpilot theme. |
 | `@Kushi tour <project> [--top N]` | standard+ | n/a (read-only) | v5.0.0 — `tour` writes `<project>/State/tour.md`, an auto-generated week-in-review walkthrough scored by `recency_weight × cross_ref_count` (14-day half-life). Default N=10. |
+| `@Kushi lint <project>` | standard+ | n/a (read-only) | v5.1.0 — `lint-state` runs wiki-lint checks against `State/` (contradictions, stale claims, orphans, missing cross-refs, data gaps). Writes `State/reports/lint-YYYY-MM-DD.md`. |
 | `@Kushi consolidate <project> last N days` | core+ | N days | `consolidate-evidence` only |
 | `@Kushi status <project>` | core+ | n/a | `project-status` — show run-log |
 | `@Kushi ask <project> <question>` | core+ | n/a (read-only) | `ask-project` — cited Q&A over Evidence/ (+ State/ on full) |
@@ -50,6 +51,9 @@ The Evidence/ folder produced by `aggregate` is the **public contract** between
 | `@Kushi fde-triage <project>` | **standard+** | n/a (read-only) | `fde-triage` — full 7-file triage bundle at `Reports/triage/<YYYY-MM-DD>/` |
 | `@Kushi propose ado <project>` | **preview** | n/a (read-only) | `propose-ado-update` — generates `<engagement-root>/ado-updates/<YYYY-MM-DD>/proposed.md` from latest `_Consolidated/`. NO ADO writes. |
 | `@Kushi apply ado <project>` | **preview** | n/a (gated) | `apply-ado-update` — gated apply skill. v0.1.0-preview is dry-mode only (writes `planned.jsonl`, no real ADO calls). Governed by `update-ledger.instructions.md`. |
+| `@Kushi teach <topic>` | standard+ | n/a (write-only) | v5.2.0 — `teach` — persist a reusable fact/preference/pattern to `.kushi/learnings/`. Lookup via `explain`. |
+| `@Kushi explain <topic>` | standard+ | n/a (read-only) | v5.2.0 — `teach` (explain mode) — retrieve a previously taught fact/preference/pattern from `.kushi/learnings/`. |
+| `@Kushi schema-evolve <project>` | standard+ | n/a | v5.2.0 — `schema-evolve` — detect schema drift in Evidence/ layouts and propose safe migrations with rollback plans. |
 
 **Note on auto-routing**: `ask` does NOT require the `@Kushi ask` prefix. Any message that names a known project AND asks a question (what / who / when / status / summarize / etc.) auto-dispatches to `ask-project`. Producer verbs win in the unambiguous case.
 

package/plugin/instructions/hooks.instructions.md

@@ -0,0 +1,84 @@
+# Hooks system
+
+> Doctrine: `hooks.instructions.md` — kushi v5.2.0+
+
+## Purpose
+
+Hooks are user-configurable scripts or webhooks triggered **after** kushi pipeline events. They enable integrations (Teams notifications, ticket updates, dashboards) without modifying kushi's core skills.
+
+## Events
+
+| Event | Fires after | Payload keys |
+|-------|-------------|--------------|
+| `post-pull` | Each `pull-*` completes (per source) | `project`, `alias`, `source`, `items_pulled`, `duration_ms`, `success` |
+| `post-state` | `build-state` completes | `project`, `alias`, `pages_written`, `contradictions_flagged`, `duration_ms` |
+| `post-contradiction` | A new contradiction is flagged inside `build-state` | `project`, `alias`, `entity`, `field`, `old_value`, `new_value`, `source` |
+| `post-lint` | `lint-state` completes | `project`, `alias`, `findings_count`, `report_path`, `duration_ms` |
+
+## Configuration
+
+Hooks are declared per-project at:
+- `.kushi/hooks.yml` — webhook URLs + settings
+- `.kushi/hooks/<event>.ps1` — PowerShell hook scripts
+
+### `.kushi/hooks.yml` schema
+
+```yaml
+hooks:
+  post-pull:
+    - type: webhook
+      url: https://example.webhook.office.com/...
+      timeout_ms: 5000
+    - type: script
+      path: .kushi/hooks/post-pull.ps1
+  post-state:
+    - type: webhook
+      url: https://...
+  post-contradiction:
+    - type: script
+      path: .kushi/hooks/post-contradiction.ps1
+  post-lint: []
+```
+
+### PowerShell hooks
+
+- Receive the event payload as JSON on **stdin**.
+- Exit 0 = success; non-zero = logged warning (never blocks pipeline).
+- Timeout: 30s default (configurable per hook via `timeout_ms`).
+- Working directory: project root.
+
+### Webhook hooks
+
+- Payload sent as HTTP POST body (`Content-Type: application/json`).
+- Timeout: 5000ms default.
+- Non-2xx response = logged warning (never blocks).
+
+## Execution semantics
+
+1. **Warn-only**: Hook failures are logged to `Evidence/<alias>/State/hooks-log.md` but NEVER block the pipeline.
+2. **Order**: Hooks for the same event fire sequentially in declaration order.
+3. **Idempotent dispatch**: `Invoke-Hooks` is safe to call multiple times — the log deduplicates by event+timestamp.
+4. **No content**: Hooks receive metadata only. Evidence content is NEVER included in payloads (privacy).
+
+## CLI verbs
+
+- `kushi hooks list <project>` — list configured hooks for a project.
+- `kushi hooks test <project> <event>` — fire a synthetic event payload.
+
+## Output
+
+Hook invocations are logged to `Evidence/<alias>/State/hooks-log.md` with format:
+
+```markdown
+## [2026-05-29 14:30] post-pull | hook: teams-notify
+
+- status: success
+- duration_ms: 342
+- target: https://example.webhook.office.com/...
+```
+
+## References
+
+- `Invoke-Hooks.ps1` — shared helper (`plugin/skills/_shared/Invoke-Hooks.ps1`)
+- `log-format.instructions.md` — log entry format
+- `living-wiki.instructions.md` — contradiction events trigger `post-contradiction`

package/plugin/instructions/living-wiki.instructions.md

@@ -0,0 +1,88 @@
+---
+name: "living-wiki"
+description: "v5.1.0 — Incremental-maintenance + contradiction-handling pattern for State/. Build-state preserves human edits outside <!-- kushi:auto --> fences; contradictions are flagged with callouts, never silently overwritten. Adapted from Karpathy's living-wiki gist. Authored to agentskills.io spec; deltas: adds incremental fencing convention + contradiction lifecycle + auto-resolve threshold not present in source."
+applies_to: "build-state, lint-state, all writers touching State/"
+since: "kushi v5.1.0"
+---
+
+# living-wiki — doctrine
+
+> **Authored to [agentskills.io](https://agentskills.io/skill-creation/best-practices) spec.**
+> Deltas from source (Karpathy's living-wiki gist): adds `<!-- kushi:auto -->` fencing convention, contradiction lifecycle (current → contradicted → superseded), auto-resolve threshold with 3 conditions, `_review-queue.md` open-contradiction tracker.
+
+Adapted from [Karpathy's living-wiki gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). The core insight: a wiki maintained by both humans and machines must have clear ownership boundaries and explicit conflict resolution — silent overwrites destroy trust.
+
+## Rules (HARD)
+
+### 1. Incremental maintenance
+
+Every writer skill that touches `State/` MUST:
+
+- **Preserve human edits.** Content outside `<!-- kushi:auto:start -->` / `<!-- kushi:auto:end -->` fences is NEVER modified by automation. Writers only update derived sections between those fences.
+- **Never wipe the page.** If a page exists, read it first. Regenerate only the fenced regions. If the page does not exist, create it with fences around any auto-derived content.
+- **Fence hygiene.** Every auto-derived block MUST be wrapped:
+  ```markdown
+  <!-- kushi:auto:start section="<section-id>" -->
+  ...auto-derived content...
+  <!-- kushi:auto:end section="<section-id>" -->
+  ```
+  The `section` attribute identifies which derivation produced this block (e.g., `section="entity-summary"`, `section="related-entities"`).
+
+### 2. Contradiction handling
+
+When a new fact contradicts an existing claim (different value for the same entity property):
+
+- **Flag both claims** with Obsidian-compatible callouts:
+  ```markdown
+  > [!warning] Contradicted by build-state run 2026-05-28
+  > Previous value: "MACC $500K" [source: ushak/crm/weekly/2026-05-01_crm-csc.md#acme-opp · 2026-05-01]
+  
+  > [!info] New value (2026-05-28)
+  > Current value: "MACC $750K" [source: ushak/crm/weekly/2026-05-22_crm-csc.md#acme-opp · 2026-05-22]
+  ```
+- **Never silently overwrite.** The old value stays visible until explicitly resolved.
+- **Add to `_review-queue.md`** with entity, property, old value, new value, both sources, and date flagged.
+
+### 3. Contradiction lifecycle
+
+Each contradicted claim moves through states:
+
+| State | Meaning |
+|---|---|
+| `current` | Active, accepted truth. |
+| `contradicted` | A newer claim disagrees. Both are visible. |
+| `superseded` | Resolved — old claim is archived. The newer (or human-chosen) value wins. |
+
+### 4. Auto-resolve threshold
+
+A contradicted claim MAY be automatically marked `superseded` (and removed from `_review-queue.md`) when ALL of:
+
+1. The new claim has **≥ 3 corroborating sources from different surfaces** (e.g., meetings + CRM + email all agree on the new value).
+2. The contradicted claim is **≥ 30 days old** (based on its source citation date).
+3. The contradicted claim has **no human override marker** (`<!-- kushi:human-override -->` above the claim blocks auto-resolve).
+
+When auto-resolved, replace the callout pair with:
+```markdown
+> [!info] Auto-resolved 2026-06-28 — superseded by 3+ corroborating sources (meetings, crm, email)
+> Previous value archived: "MACC $500K" [source: ...]
+```
+
+### 5. `_review-queue.md`
+
+Located at `Evidence/<alias>/State/_review-queue.md`. Lists all open (unresolved) contradictions:
+
+```markdown
+# Review Queue
+
+| Entity | Property | Old value | New value | Flagged | Sources |
+|---|---|---|---|---|---|
+| Acme Opp | MACC | $500K | $750K | 2026-05-28 | crm, meetings |
+```
+
+Updated by `build-state` on every run. Cleared when contradictions are resolved (auto or manual).
+
+## References
+
+- [Karpathy's living-wiki gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
+- `karpathy-state-layout.instructions.md` (v5.0.0 base layout)
+- `wiki-lint.instructions.md` (contradiction-flagged finding class)

package/plugin/instructions/log-format.instructions.md

@@ -0,0 +1,78 @@
+---
+name: "log-format"
+description: "v5.1.0 — Canonical log format for State/log.md. Every writer appends reverse-chronological entries with grep-friendly headings. Adapted from axoviq-ai/synthadoc log-as-history pattern. Authored to agentskills.io spec; deltas: kushi-specific ops taxonomy, index.md 'Last touched' pointer, append-only rule."
+applies_to: "every writer skill that touches State/ (bootstrap-project, refresh-project, build-state, lint-state, link-entities, dashboard, tour, ask-project --file-back)"
+since: "kushi v5.1.0"
+---
+
+# log-format — doctrine
+
+> **Authored to [agentskills.io](https://agentskills.io/skill-creation/best-practices) spec.**
+> Deltas from source (axoviq-ai/synthadoc): kushi-specific op taxonomy (`bootstrap`, `refresh`, `build-state`, `lint-state`, `ask-fileback`, `link-entities`, `dashboard`, `tour`), `index.md` "Last touched" pointer, reverse-chronological append-only rule.
+
+Adapted from [axoviq-ai/synthadoc](https://github.com/axoviq-ai/synthadoc) — the log-as-grep-friendly-history pattern.
+
+## Rules (HARD)
+
+### 1. Canonical format
+
+Every entry in `Evidence/<alias>/State/log.md` MUST use this heading format:
+
+```markdown
+## [YYYY-MM-DD HH:MM] <op> | <title>
+
+<1–3 line summary>
+Sources: <comma-separated source pointers>
+```
+
+Example:
+```markdown
+## [2026-05-28 14:30] build-state | Incremental rebuild (3 entities updated)
+
+Re-derived people/jane-doe.md, decisions/macc-increase.md, risks/timeline-slip.md.
+Contradictions flagged: 1 (Acme Opp MACC). Auto-resolved: 0.
+Sources: ushak/crm/weekly/2026-05-22_crm-csc.md, ushak/meetings/weekly/2026-05-21_meetings-csc.md
+```
+
+### 2. Grep-friendly
+
+The heading format is designed for grep:
+```bash
+grep '^## \[2026-05-' log.md          # all May 2026 entries
+grep '^## \[.*\] build-state' log.md   # all build-state runs
+grep '^## \[.*\] lint-state' log.md    # all lint runs
+```
+
+### 3. Ops taxonomy (closed set)
+
+| Op | Writer skill | Meaning |
+|---|---|---|
+| `bootstrap` | bootstrap-project | First-time project setup |
+| `refresh` | refresh-project | Incremental evidence pull + state rebuild |
+| `build-state` | build-state | Pure re-render of State/ from Evidence/ |
+| `lint-state` | lint-state | Wiki lint pass over State/ |
+| `ask-fileback` | ask-project --file-back | Q&A answer written back to State/answers/ |
+| `link-entities` | link-entities | Cross-source graph rebuild |
+| `dashboard` | dashboard | Dashboard HTML regeneration |
+| `tour` | tour | Guided tour regeneration |
+
+### 4. Append-only, reverse-chronological
+
+- New entries are **prepended** (newest at top, after the front-matter and file header).
+- Entries are NEVER deleted or rewritten.
+- Readers scan top-down for recency.
+
+### 5. Index.md "Last touched" pointer
+
+After appending to `log.md`, the writer MUST also update the top of `State/index.md`:
+
+```markdown
+> Last touched: YYYY-MM-DD HH:MM by <op> ([log](log.md))
+```
+
+This single-line pointer lives immediately after the front-matter block of `index.md`.
+
+## References
+
+- [axoviq-ai/synthadoc](https://github.com/axoviq-ai/synthadoc)
+- `karpathy-state-layout.instructions.md` (log.md base contract)