kushi-agents 5.1.0 → 5.3.0

package/README.md

@@ -7,6 +7,8 @@
 [![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.*.
@@ -93,6 +95,89 @@ To use: point Obsidian at `<project>/State/` as a vault. The `index.md` serves a
 
 ---
 
+## 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.
+
+---
+
+## Global wiki (v5.3.0+)
+
+A per-user **global wiki** at `~/.kushi-global/State/` for cross-engagement knowledge — same Karpathy shape as a project `State/`, marked `scope: global`.
+
+```bash
+kushi global init                     # scaffold ~/.kushi-global/State/
+kushi global status                   # counts + last-modified summary
+kushi global ask "what's our confidence ladder pattern?"
+kushi global lint                     # privacy + structure pass
+
+# Project → global is explicit-only:
+kushi promote <project> <answer-page>          # refuses if identifiers detected
+kushi promote <project> <answer-page> --force  # redacts + writes target + back-link
+
+# Routing under ask-project:
+kushi ask <project> "..."                     # project-first (default)
+kushi ask <project> "..." --global            # global-first
+kushi ask <project> "..." --project-only      # suppress global
+```
+
+The global root honors `$KUSHI_GLOBAL_ROOT` (used by tests). There is no auto-promotion path — privacy is always your call. See `plugin/instructions/global-wiki.instructions.md` + `plugin/instructions/multi-wiki-routing.instructions.md`.
+
+---
+
 ## Three install profiles
 
 Kushi ships in three tiers. Pick how much you take — the default (`standard`) matches v2.x behavior end-to-end.

package/bin/cli.mjs

@@ -17,15 +17,89 @@ if (args.length > 0 && SKILL_VERBS.has(args[0])) {
 
 // ── lint verb (v5.1.0+) ──────────────────────────────────────────────────────
 if (args.length > 0 && args[0] === 'lint') {
+  if (args.includes('--global')) {
+    const { runGlobalLint } = await import('../src/global-wiki-cli.mjs');
+    await runGlobalLint();
+    process.exit(0);
+  }
   const project = args[1] || '';
   if (!project) {
-    console.error('\n  Usage: kushi lint <project>\n');
+    console.error('\n  Usage: kushi lint <project>\n         kushi lint --global\n');
     process.exit(1);
   }
   await dispatchLint(project);
   process.exit(0);
 }
 
+// ── global verb (v5.3.0+) ────────────────────────────────────────────────────
+if (args.length > 0 && args[0] === 'global') {
+  const sub = args[1] || '';
+  const validSubs = ['init', 'status', 'ask', 'lint'];
+  if (!validSubs.includes(sub)) {
+    console.error('\n  Usage: kushi global init           Scaffold ~/.kushi-global/State/');
+    console.error('         kushi global status         Show counts + freshness');
+    console.error('         kushi global ask <question> Ask the global wiki');
+    console.error('         kushi global lint           Lint the global wiki\n');
+    process.exit(1);
+  }
+  const { runGlobalInit, runGlobalStatus, runGlobalAsk, runGlobalLint } = await import('../src/global-wiki-cli.mjs');
+  if (sub === 'init') await runGlobalInit();
+  else if (sub === 'status') await runGlobalStatus();
+  else if (sub === 'ask') await runGlobalAsk(args.slice(2).join(' '));
+  else if (sub === 'lint') await runGlobalLint();
+  process.exit(0);
+}
+
+// ── promote verb (v5.3.0+) ───────────────────────────────────────────────────
+if (args.length > 0 && args[0] === 'promote') {
+  const project = args[1] || '';
+  const page = args[2] || '';
+  if (!project || !page) {
+    console.error('\n  Usage: kushi promote <project> <page-path>\n');
+    console.error('  Copies a project State page into the global wiki with provenance metadata.');
+    console.error('  Refuses by default if customer identifiers are detected; pass --force after review.\n');
+    process.exit(1);
+  }
+  const force = args.includes('--force');
+  const { runPromote } = await import('../src/global-wiki-cli.mjs');
+  await runPromote(project, page, { force });
+  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]
@@ -74,6 +148,21 @@ if (args.includes('--help') || args.includes('-h')) {
 
   Wiki maintenance (v5.1.0+):
     lint <project>       Run wiki-lint checks on State/ (contradictions, stale claims, orphans).
+    lint --global        Lint the global wiki at ~/.kushi-global/State/.
+
+  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.
+
+  Global wiki (v5.3.0+):
+    global init                    Scaffold ~/.kushi-global/State/ (env: KUSHI_GLOBAL_ROOT)
+    global status                  Show page counts + freshness for the global wiki.
+    global ask <question>          Search the global wiki specifically.
+    global lint                    Lint the global wiki (alias for 'lint --global').
+    promote <project> <page>       Move a project State page into global with redaction + back-link.
+                                   Refuses if customer identifiers are detected; --force after review.
 
   After install, talk to Kushi:
     bootstrap <project>     First-time setup
@@ -279,3 +368,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.1.0",
+  "version": "5.3.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 src/global-wiki.test.mjs src/promote.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

@@ -51,6 +51,11 @@ 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. |
+| `@Kushi global init` / `status` / `ask <q>` / `lint` | standard+ | n/a | v5.3.0 — `global-wiki` — manage the per-user cross-engagement wiki at `~/.kushi-global/State/` (env `KUSHI_GLOBAL_ROOT` for tests). |
+| `@Kushi promote <project> <page>` | standard+ | n/a | v5.3.0 — `promote` — copy a project State page into the global wiki with identifier redaction + back-link + dual log. Refuses without `--force` when identifiers detected. |
 
 **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/global-wiki.instructions.md

@@ -0,0 +1,79 @@
+---
+name: "global-wiki"
+description: "v5.3.0 — Global wiki at ~/.kushi-global/State/ (env override KUSHI_GLOBAL_ROOT). Structurally identical to a project State/ wiki (Karpathy layout) but tagged scope: global in frontmatter. Holds cross-engagement patterns that don't belong in any one project. Never auto-populated — only explicit kushi promote moves content in. Linter checks for [!warning] potential-customer-leak callouts to enforce privacy posture."
+applies_to: "global init/status/ask/lint, promote, ask-project routing, teach routing"
+since: "kushi v5.3.0"
+---
+
+# global-wiki — doctrine
+
+> **Authored to [agentskills.io](https://agentskills.io/skill-creation/best-practices) spec.**
+> Deltas from source (living-wiki Karpathy pattern + Obsidian global-vault + Claude.md global-memory): adds a separate root, `scope: global` frontmatter marker, explicit-promotion-only contract, and a privacy linter (`potential-customer-leak`).
+
+The global wiki is a personal, cross-engagement knowledge base that lives **outside** any single project's `Evidence/<alias>/State/`. Consultants accumulate cross-cutting patterns — "how I structure FDE intake", "my preferred Status taxonomy", "tools and snippets that work across all customers" — and those patterns belong in a single durable home, not re-derived per engagement and not silently bleeding between projects.
+
+## Rules (HARD)
+
+### 1. Location
+
+- **Default:** `~/.kushi-global/State/` (`$HOME` on POSIX, `$env:USERPROFILE` on Windows).
+- **Override:** `$KUSHI_GLOBAL_ROOT` environment variable (absolute path; tilde-expanded). Tests MUST set this to `.testtmp/.kushi-global/` — never touch the real path.
+- The global root is **per-user**, never per-project, never per-host.
+
+### 2. Shape
+
+The global wiki MUST mirror the standard State/ layout (per `karpathy-state-layout.instructions.md` + `living-wiki.instructions.md`):
+
+```
+~/.kushi-global/State/
+├── index.md          # entry point, links to all pages
+├── log.md            # reverse-chronological op log (same format as project log.md)
+├── tour.md           # guided tour pointer (optional)
+├── hot.md            # hot-edits scratch (optional)
+├── conventions.md    # cross-engagement conventions / CLAUDE.md-shape rules
+├── answers/          # promoted Q&A pages
+├── reports/          # global lint reports, status snapshots
+└── _review-queue.md  # open privacy / contradiction items
+```
+
+Every markdown page in the global wiki MUST carry frontmatter with `scope: global`:
+
+```yaml
+---
+kushi_state_page: true
+scope: global
+---
+```
+
+The `scope: global` marker distinguishes a true global page from a project page that was *copied* locally for reference.
+
+### 3. Initialization
+
+- `kushi global init` creates the scaffold idempotently — re-running NEVER overwrites existing content.
+- Skips files that already exist; only adds missing scaffolding.
+- Logs `global-init` entry to `~/.kushi-global/State/log.md` on every run (even no-op).
+
+### 4. Privacy posture
+
+The global wiki crosses engagements. **Customer identifiers MUST NOT leak in.**
+
+- The promote operation runs an identifier scan and refuses unless explicit `--force` is given.
+- `kushi global lint` (and `kushi lint --global`) scans `*.md` under the global root for `> [!warning] potential-customer-leak` callouts (left there by promote when it had to redact).
+- The user is responsible for resolving those callouts before sharing the global wiki.
+
+### 5. Promotion is explicit only
+
+- Pages NEVER auto-promote from a project to global. The only path is `kushi promote <project> <page-path>`.
+- See `multi-wiki-routing.instructions.md` for the promotion contract + back-link rule.
+
+### 6. Storage outside engagement tree
+
+The global wiki lives **outside** any engagement root. Self-check `D40.global-wiki-shape` checks the configured location (env-overridden in CI) and is warn-only — the absence of `~/.kushi-global/` is normal until the user runs `kushi global init`.
+
+## References
+
+- `multi-wiki-routing.instructions.md` — routing across project + global
+- `living-wiki.instructions.md` — incremental + contradiction lifecycle (same rules apply)
+- `karpathy-state-layout.instructions.md` — page shape
+- `schema-evolve.instructions.md` — `global` scope was placeholdered here in v5.2.0; v5.3.0 honors it.
+- `wiki-lint.instructions.md` — finding classes; v5.3.0 adds `potential-customer-leak`.

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/multi-wiki-routing.instructions.md

@@ -0,0 +1,117 @@
+---
+name: "multi-wiki-routing"
+description: "v5.3.0 — Routing rules for project vs global wiki. ask-project: project-first; augment with global only if project confidence below threshold; --global forces global-first, --project-only suppresses global. build-state: project-only, never auto-promotes to global. lint-state: project-only; kushi lint --global lints global separately. teach: global-first for cross-cutting topics, project for project-specific. Promotion path: explicit kushi promote <project> <page>, never automatic."
+applies_to: "ask-project, build-state, lint-state, teach, promote"
+since: "kushi v5.3.0"
+---
+
+# multi-wiki-routing — doctrine
+
+> **Authored to [agentskills.io](https://agentskills.io/skill-creation/best-practices) spec.**
+> Deltas from source: kushi previously had a single wiki per project. This doctrine formalizes the project↔global routing rules introduced in v5.3.0.
+
+Kushi maintains two kinds of wikis:
+
+| Kind | Path | Scope |
+|---|---|---|
+| **Project** | `Evidence/<alias>/State/` | One engagement only. |
+| **Global** | `$KUSHI_GLOBAL_ROOT` or `~/.kushi-global/State/` | Cross-engagement; per-user. |
+
+Every reader/writer skill MUST be explicit about which it touches.
+
+## Rules (HARD)
+
+### 1. ask-project — project-first, global-augment
+
+Default behavior (`kushi ask <project> <q>`):
+
+1. Resolve the project and run the standard project-scoped answer chain (per `ask-project/SKILL.md`).
+2. Compute the confidence (per `evidence-confidence-ladder.instructions.md`).
+3. **If confidence is `low` (or `medium` with `--global-augment` set in config)** → also query `$KUSHI_GLOBAL_ROOT/State/answers/` for matching topics and append a `## From your global wiki` section, citing each hit with `[global: <page>]`.
+4. **If confidence is `high`** → do NOT consult global (avoid noise).
+
+Flags:
+
+| Flag | Behavior |
+|---|---|
+| `--global` | Reverse the order: search global first, project second. Show provenance `[global]` first, `[project: <alias>]` second. |
+| `--project-only` | Hard-disable global consultation regardless of confidence. |
+| (none) | Default project-first + augment-on-low-confidence. |
+
+Source provenance MUST be visible per citation: `[project: <alias>]` vs `[global]`.
+
+### 2. build-state — project-only
+
+`build-state` writes to `Evidence/<alias>/State/` and **NEVER** writes to the global wiki. There is no auto-promotion path. Even if a fact has appeared in 10 projects, build-state does not move it to global — only the user, via `kushi promote`, does.
+
+### 3. lint-state — project-only by default
+
+- `kushi lint <project>` → lints the project State only. Unchanged from v5.1.0.
+- `kushi lint --global` → lints the global wiki at `$KUSHI_GLOBAL_ROOT/State/` separately. Same finding classes plus `potential-customer-leak` (see `global-wiki.instructions.md`).
+- Lint runs are independent; one does not implicitly run the other.
+
+### 4. teach — global-first for cross-cutting topics
+
+- For **cross-cutting topics** (kushi concepts, doctrines, releases — e.g. "explain confidence ladder", "how does CSC work"): `teach` consults the global wiki FIRST (if a matching page exists in `~/.kushi-global/State/answers/`), then falls back to in-repo doctrine, then to genealogy.
+- For **project-specific topics** ("how did we structure intake for AGCO?"): `teach` declines and suggests `kushi ask <project> <q>` instead — that's an `ask-project` job.
+- Citations distinguish `[global: <page>]` vs `[doctrine: <file>]` vs `[genealogy: <version>]`.
+
+### 5. Promotion path — explicit only
+
+`kushi promote <project> <page>` is the **only** way content moves project → global. See `Promote operation` below.
+
+Auto-promotion is intentionally not supported because:
+
+1. Customer-identifier detection is best-effort; the user must review.
+2. What is "cross-cutting" depends on the consultant, not the machine.
+3. Silent promotion would surprise the user — global is personal space.
+
+### 6. Demotion / removal
+
+There is no `kushi demote` in v5.3.0. To remove a global page the user deletes the file directly and appends a manual `log.md` entry. v6+ MAY add a managed demote verb.
+
+## Promote operation
+
+`kushi promote <project> <page-path>` performs the following, in order:
+
+1. **Resolve source.** Find `<engagement-root>/<project>/Evidence/<alias>/State/<page-path>`. Must exist.
+2. **Read source body + frontmatter.**
+3. **Run identifier scan** against the body. Uses the same heuristics as `schema-evolve`-style detection:
+   - Known customer aliases registered in `.settings.yml` `discovery.project_aliases:` or the alias folder name itself.
+   - The literal project name.
+   - Email addresses with non-Microsoft domains.
+   - High-confidence proper-noun runs that match `<project>` aliases (case-insensitive, word boundaries).
+4. **Build redaction list.** For each hit:
+   - Replace the literal string with `[REDACTED]` in the global copy.
+   - Record `{ pattern, count, line_numbers }` in the redactions list.
+5. **Refuse without `--force`** if the redactions list is non-empty. Print the list with line numbers and the human-review prompt. The user is expected to inspect, then re-run with `--force` (which writes the redacted body and adds a `> [!warning] potential-customer-leak` callout near each redaction site for the lint pass to track).
+6. **Write target.** Path: `$KUSHI_GLOBAL_ROOT/State/answers/<source-slug>.md` (slugify source filename; collisions append `-N`).
+   Frontmatter MUST contain:
+   ```yaml
+   ---
+   kushi_state_page: true
+   scope: global
+   promoted_from: "<project>/<alias>/<relative-source-path>"
+   promoted_at: "<ISO-8601 UTC>"
+   redactions: ["<pattern1>", "<pattern2>"]
+   ---
+   ```
+7. **Add back-link to source.** Append (or update) a callout in the source page:
+   ```markdown
+   > [!info] Promoted to global wiki
+   > <source-slug>.md @ <ISO-8601 UTC> · redactions: <N>
+   ```
+8. **Dual log.** Append a `promote` entry to BOTH:
+   - `<project>/Evidence/<alias>/State/log.md` (op = `promote`, title = `Promoted <slug> to global`).
+   - `$KUSHI_GLOBAL_ROOT/State/log.md` (op = `promote-in`, title = `Imported <slug> from <project>`).
+9. **Print summary** with both file paths.
+
+The operation is **atomic**: if any step fails (redaction refused, write denied, back-link fails), no writes are persisted. The implementation uses a stage-then-commit pattern.
+
+## References
+
+- `global-wiki.instructions.md` — global wiki location + privacy rules
+- `evidence-confidence-ladder.instructions.md` — confidence threshold for routing
+- `living-wiki.instructions.md` — same incremental + contradiction rules apply to both wikis
+- `wiki-lint.instructions.md` — finding classes; v5.3.0 adds `potential-customer-leak`
+- `schema-evolve.instructions.md` — identifier-detection heuristics reused here