kushi-agents 5.1.0 → 5.2.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,65 @@ 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.
+
+---
+
 ## 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

@@ -26,6 +26,40 @@ if (args.length > 0 && args[0] === 'lint') {
   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]
@@ -75,6 +109,12 @@ if (args.includes('--help') || args.includes('-h')) {
   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/
@@ -279,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.1.0",
+  "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

@@ -51,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/otel.instructions.md

@@ -0,0 +1,75 @@
+# OpenTelemetry export
+
+> Doctrine: `otel.instructions.md` — kushi v5.2.0+
+
+## Purpose
+
+Opt-in observability for kushi pipelines via OpenTelemetry Protocol (OTLP). Enables enterprise teams to trace kushi runs in their existing observability stack (Jaeger, Grafana Tempo, Azure Monitor, Datadog, etc.).
+
+## Opt-in activation
+
+Set the environment variable:
+
+```
+KUSHI_OTEL_ENDPOINT=http://localhost:4318/v1/traces
+```
+
+When unset or empty, all OTel helpers are **no-ops** with zero overhead (no HTTP calls, no object allocation beyond the guard check).
+
+## Events emitted
+
+| Span name | Fires during | Attributes |
+|-----------|-------------|------------|
+| `kushi.pull` | Each `pull-*` source | `project`, `alias`, `source`, `duration_ms`, `success`, `evidence_count` |
+| `kushi.build_state` | `build-state` | `project`, `alias`, `pages_written`, `contradictions_flagged`, `duration_ms`, `success` |
+| `kushi.lint` | `lint-state` | `project`, `alias`, `findings_count`, `duration_ms`, `success` |
+| `kushi.contradiction.flagged` | Inside `build-state` when a new contradiction is detected | `project`, `alias`, `entity`, `field`, `source` |
+| `kushi.hook.invoked` | Each hook invocation | `project`, `alias`, `event`, `hook_type`, `target`, `duration_ms`, `success` |
+
+## Wire format
+
+Uses the [OTLP/HTTP JSON](https://opentelemetry.io/docs/specs/otlp/#otlphttp) format:
+- Endpoint: `$KUSHI_OTEL_ENDPOINT` (must include path, e.g. `/v1/traces`)
+- Method: POST
+- Content-Type: `application/json`
+- No external dependencies — pure PowerShell via `Invoke-RestMethod`
+
+## Privacy contract
+
+**CRITICAL**: OTel spans carry ONLY:
+- Operation metadata (names, counts, durations, success/failure)
+- Project/alias identifiers
+
+OTel spans NEVER carry:
+- Evidence content (email bodies, meeting transcripts, etc.)
+- PII (user emails, file paths with usernames beyond alias)
+- Authentication tokens or secrets
+
+This is enforced structurally: `Emit-OtelSpan.ps1` accepts only a fixed set of attribute keys.
+
+## Implementation
+
+The shared helper `plugin/skills/_shared/Emit-OtelSpan.ps1`:
+1. Checks `$env:KUSHI_OTEL_ENDPOINT` — returns immediately if unset/empty.
+2. Constructs a minimal OTLP JSON payload with a single span.
+3. POSTs via `Invoke-RestMethod` with a 5s timeout.
+4. On failure: logs a warning to stderr, never throws, never blocks the pipeline.
+
+## Service identity
+
+```json
+{
+  "resource": {
+    "attributes": [
+      { "key": "service.name", "value": { "stringValue": "kushi" } },
+      { "key": "service.version", "value": { "stringValue": "<package.json version>" } }
+    ]
+  }
+}
+```
+
+## References
+
+- `Emit-OtelSpan.ps1` — shared helper (`plugin/skills/_shared/Emit-OtelSpan.ps1`)
+- `hooks.instructions.md` — hook invocations emit `kushi.hook.invoked` spans
+- `parallel-execution.instructions.md` — parallel pulls emit one span per worker

package/plugin/instructions/parallel-execution.instructions.md

@@ -0,0 +1,81 @@
+# Parallel execution
+
+> Doctrine: `parallel-execution.instructions.md` — kushi v5.2.0+
+
+## Purpose
+
+Defines when and how kushi parallelizes work. The primary use case is parallel `pull-*` dispatch during `refresh-project`, but the patterns apply to any future parallel workload.
+
+## When to parallelize
+
+| Scenario | Parallel? | Why |
+|----------|-----------|-----|
+| Multiple `pull-*` in a refresh | ✅ Yes | Sources are independent; each writes to its own `Evidence/<alias>/<source>/` subtree |
+| `build-state` page writes | ❌ No | Pages may reference each other; deterministic ordering required |
+| `lint-state` finding checks | ✅ Yes (future) | Read-only checks are embarrassingly parallel |
+| Hook dispatch | ❌ No | Sequential for predictable log ordering |
+
+## Configuration
+
+In `.kushi/config.yml` (project-level) or `~/.kushi/config.yml` (user-level):
+
+```yaml
+parallel:
+  max_workers: 4        # default; 1 = sequential
+  throttle_ms: 200      # minimum delay between worker starts (rate-limit courtesy)
+```
+
+Override at runtime: `kushi refresh <project> --sequential` forces `max_workers: 1`.
+
+## Throttling considerations
+
+M365 Graph (via WorkIQ) enforces per-user rate limits:
+- **429 Too Many Requests** — back off exponentially.
+- Kushi's `throttle_ms` provides a minimum inter-start delay (not a per-request throttle — individual pull-* skills handle their own retries via `auth-and-retry.instructions.md`).
+- Default 200ms is conservative; increase for tenants with aggressive throttling.
+
+## Error aggregation
+
+- Each worker runs independently. A failure in `pull-email` does NOT halt `pull-teams`.
+- Worker results are collected into a `Map<source, {status, items, duration, error?}>`.
+- After all workers complete, results are sorted in **canonical source order** (same order as sequential dispatch per `refresh-project/SKILL.md` Step 2).
+- The run summary and run-log entries are written in canonical order regardless of completion order.
+
+## Deterministic output ordering
+
+Despite parallel execution, all observable outputs (run-log entries, refresh report tables, State/log.md entries) are written in **canonical source order**:
+
+1. pull-email
+2. pull-teams
+3. pull-meetings
+4. pull-onenote
+5. pull-loop
+6. pull-sharepoint
+7. pull-crm
+8. pull-ado
+9. pull-misc
+
+This ensures `git diff` is stable across runs and self-check D38 passes.
+
+## Implementation pattern (PowerShell)
+
+```powershell
+# Worker pool using Start-ThreadJob (PowerShell 7+)
+$maxWorkers = $config.parallel.max_workers ?? 4
+$throttleMs = $config.parallel.throttle_ms ?? 200
+$jobs = @()
+foreach ($source in $enabledSources) {
+    while (($jobs | Where-Object { $_.State -eq 'Running' }).Count -ge $maxWorkers) {
+        Start-Sleep -Milliseconds 100
+    }
+    $jobs += Start-ThreadJob -ScriptBlock { param($s) & pull-$s ... } -ArgumentList $source
+    Start-Sleep -Milliseconds $throttleMs
+}
+$results = $jobs | Receive-Job -Wait -AutoRemoveJob
+```
+
+## References
+
+- `refresh-project/SKILL.md` — orchestrator that dispatches parallel pulls
+- `auth-and-retry.instructions.md` — per-request throttling within each worker
+- `hooks.instructions.md` — hooks fire AFTER parallel aggregation completes

package/plugin/instructions/schema-evolve.instructions.md

@@ -0,0 +1,73 @@
+# Schema evolve
+
+> Doctrine: `schema-evolve.instructions.md` — kushi v5.2.0+
+
+## Purpose
+
+Allows users to teach kushi project-specific conventions that persist across runs. When a user says "from now on always do X for this project," kushi captures the rule and applies it in all future operations.
+
+## Storage location
+
+Rules are stored in `Evidence/<alias>/State/CLAUDE.md` under the project's evidence tree.
+
+**Decision rationale**: `CLAUDE.md` is the Karpathy-pattern file for agent-specific conventions (already present in the State layout since v5.0.0). Placing rules here means:
+- They're versioned alongside evidence (git-tracked engagement roots get history).
+- They're co-located with the State pages that apply them.
+- They're readable by any agent (not kushi-specific format).
+
+## Rule format
+
+Rules are appended to `CLAUDE.md` with structure:
+
+```markdown
+## Rule: <short-title>
+
+- **Added**: 2026-05-29T14:30:00Z
+- **Scope**: project | alias | global
+- **Source**: user (natural language) | schema-evolve skill
+
+<rule text as stated by the user>
+```
+
+## Scope levels
+
+| Scope | Stored at | Applies to |
+|-------|-----------|------------|
+| `project` | `Evidence/<alias>/State/CLAUDE.md` | All operations on this project |
+| `alias` | `Evidence/<alias>/State/CLAUDE.md` | Only this contributor's operations |
+| `global` | `~/.kushi/conventions.md` | All projects (future — v5.3.0) |
+
+v5.2.0 implements `project` scope only. `alias` and `global` are documented for forward compatibility.
+
+## How rules are applied
+
+1. At the start of `build-state`, `ask-project`, and `refresh-project`, the skill reads `Evidence/<alias>/State/CLAUDE.md`.
+2. Rules are parsed into a list and included as context for the operation.
+3. Rules affect preferences (formatting, naming, emphasis) but NEVER override hard doctrine (WorkIQ-only, verbatim-by-default, CSC format).
+
+## Conflict resolution
+
+- Hard doctrine always wins over user rules.
+- Later rules override earlier rules on the same topic.
+- If a rule contradicts doctrine, it's logged as a warning but not applied.
+
+## CLI verb
+
+`kushi remember <rule>` — captures a rule at project scope.
+
+Auto-detection: when the user says "from now on...", "always...", "never...", "for this project..." in `ask-project`, the skill offers to persist it as a convention.
+
+## Examples
+
+```
+> kushi remember "always use 'HCA' not 'Healthcare Accelerator' in summaries"
+> kushi remember "treat John Smith as the primary EM for this project"
+> kushi remember "CRM entity 'opportunity' maps to our internal term 'deal'"
+```
+
+## References
+
+- `karpathy-state-layout.instructions.md` — CLAUDE.md file in State layout
+- `living-wiki.instructions.md` — rules interact with incremental State maintenance
+- `build-state` skill — reads rules at start of run
+- `ask-project` skill — reads rules + offers to capture new ones