kushi-agents 5.9.4 → 5.9.7

package/bin/cli.mjs

@@ -5,6 +5,62 @@ import { runMultiHost } from '../src/multi-host.mjs';
 
 const args = process.argv.slice(2);
 
+// ── verb aliases (v5.9.6+) ──────────────────────────────────────────────────
+// Natural-language synonyms for the canonical verbs. Keeps `kushi update HCA`
+// / `kushi pull HCA` / `kushi sync HCA` / etc. from confusing humans + agents.
+const VERB_ALIASES = {
+  // refresh-equivalents
+  'update':         'refresh',
+  'pull':           'refresh',
+  'sync':           'refresh',
+  'regenerate':     'refresh',
+  'refresh-runner': 'refresh',  // back-compat with v5.9.0–v5.9.5 internal name
+  // bootstrap-equivalents
+  'init':             'bootstrap',
+  'new':              'bootstrap',
+  'bootstrap-runner': 'bootstrap', // back-compat
+};
+if (args.length > 0 && VERB_ALIASES[args[0]]) {
+  args[0] = VERB_ALIASES[args[0]];
+}
+
+// ── alias resolution (v5.9.7+) ──────────────────────────────────────────────
+// Mirrors `instructions/identity-resolution.instructions.md`: read alias from
+// <cwd>/.kushi/config/user/project-evidence.yml, with KUSHI_ALIAS env override.
+// No silent git-email derivation, no Graph fallback — same rules as chat.
+async function resolveAlias() {
+  if (process.env.KUSHI_ALIAS && process.env.KUSHI_ALIAS.trim()) {
+    return { alias: process.env.KUSHI_ALIAS.trim(), source: 'env' };
+  }
+  const fs = await import('node:fs');
+  const path = await import('node:path');
+  const cfgPath = path.resolve(process.cwd(), '.kushi', 'config', 'user', 'project-evidence.yml');
+  if (!fs.existsSync(cfgPath)) return { alias: null, source: 'missing-config' };
+  try {
+    const txt = fs.readFileSync(cfgPath, 'utf-8');
+    const m = txt.match(/^\s*alias:\s*([^\s#]+)/m);
+    if (!m) return { alias: null, source: 'no-alias-key' };
+    const v = m[1].trim();
+    if (!v || v === '<auto>' || v.startsWith('<') || v === 'your-alias') {
+      return { alias: null, source: 'placeholder' };
+    }
+    return { alias: v, source: 'project-evidence.yml' };
+  } catch {
+    return { alias: null, source: 'read-error' };
+  }
+}
+
+function printAliasError(verb, project) {
+  console.error(`\n  Couldn't resolve your alias — needed for the deterministic runner.`);
+  console.error(`\n  The runner writes evidence into Evidence/<alias>/, so it must know who you are.`);
+  console.error(`\n  Fix one of these (any works):`);
+  console.error(`    • cd to a workspace that already has .kushi/ installed (run from there)`);
+  console.error(`    • Run \`kushi setup\` to seed your identity in this workspace`);
+  console.error(`    • Set the env var:  $env:KUSHI_ALIAS = '<your-alias>'    (PowerShell)`);
+  console.error(`                       export KUSHI_ALIAS=<your-alias>      (bash)`);
+  console.error(`    • Run from VS Code Copilot Chat instead:  @Kushi ${verb} ${project}\n`);
+}
+
 // ── bare invocation ──────────────────────────────────────────────────────────
 // Two bins share this cli (via thin wrappers in bin/kushi.mjs and
 // bin/kushi-agents.mjs that set KUSHI_BIN_NAME). Behavior diverges on no-args:
@@ -33,6 +89,22 @@ if (args.length === 0) {
   process.exit(0);
 }
 
+// ── version flag (v5.9.5+) ──────────────────────────────────────────────────
+// `kushi --version` / `-v` / `version` → print version and exit. Previously
+// these fell through to the installer's main() which printed the banner and
+// started the install flow.
+if (args.length > 0 && (args[0] === '--version' || args[0] === '-v' || args[0] === 'version')) {
+  const pathMod = await import('node:path');
+  const urlMod = await import('node:url');
+  const fsMod = await import('node:fs');
+  const here = pathMod.dirname(urlMod.fileURLToPath(import.meta.url));
+  const repoRoot = pathMod.resolve(here, '..');
+  let version = 'unknown';
+  try { version = JSON.parse(fsMod.readFileSync(pathMod.join(repoRoot, 'package.json'), 'utf-8')).version; } catch {}
+  console.log(version);
+  process.exit(0);
+}
+
 // ── doctor verb (v5.4.0+) ───────────────────────────────────────────────────
 if (args.length > 0 && args[0] === 'doctor') {
   const { spawnSync } = await import('node:child_process');
@@ -226,43 +298,56 @@ Usage:  kushi [COMMAND] [ARGS...]
 
 Kushi v${version} — multi-source M365 project evidence + Q&A agent.
 
-Common Commands:
-  bootstrap <project>        First-time setup for a project (full pull)
-  refresh <project>          Incremental refresh + rebuild State/
-  ask <project> <question>   Cited Q&A over Evidence/ (auto-routes; --file-back to save)
-  status <project>           Show run-log for a project
-  wiki                       Resolve + scaffold + open the global wiki (one-shot)
-  doctor                     Aggregated health check (env, drift, evals, etc.)
-
-Project Commands:
-  state <project>            Re-render State/ from existing Evidence
-  references <project>       Refresh shared references pool from Evidence URLs
-  consolidate <project>      Merge per-user evidence into _Consolidated
-  lint <project>             Run wiki-lint checks on State/
-  promote <project> <page>   Move a project page into the global wiki (with redaction)
-  setup [<project>]          Run the onboarding wizard / fill missing config
-
-Global Wiki Commands:
-  global init                Scaffold ~/.kushi-global/State/ (or KUSHI_GLOBAL_ROOT)
-  global status              Page counts + freshness
-  global ask <question>      Search the global wiki specifically
-  global lint                Privacy + freshness scan
-  global show-root           Show the 4-tier resolution chain
-  global set-root <path>     Persist globalRoot (--scope workspace|home)
-  global migrate <new-path>  Copy State/ to a new root + re-persist
-
-Lifecycle Commands:
-  upgrade                    npm i -g kushi-agents@latest then re-seed assets in cwd
-  uninstall [--keep-config]  Remove <cwd>/.kushi/ (preserves Evidence/, State/)
-
-Authoring Commands:
-  create-skill <name>        Scaffold a new plugin/skills/<name>/ tree
-  check-skill <name|--all>   Lint a skill (or all skills) against the blueprint
-  optimize-description <s>   Rewrite a skill's description per optimizer rules
-  review-evals <skill>       Render an HTML eval-review viewer
-  explain <topic>            Explain a kushi concept (read-only)
-  remember <rule>            Persist a project convention to CLAUDE.md
-  hooks list|test <project>  Inspect or fire hook events
+CLI Commands (run from your shell):
+
+  Project pipeline (deterministic runners):
+    bootstrap <project>      First-time pull for a project (alias: init, new)
+    refresh <project>        Incremental refresh (alias: update, pull, sync, regenerate)
+    state <project>          Re-render State/ from existing Evidence
+    references <project>     Refresh shared references pool from Evidence URLs
+    discover <project>       Discover M365 hints (sections, chats) for a project
+
+  Project lifecycle:
+    setup [<project>]        Run the onboarding wizard / fill missing config
+    promote <project> <page> Move a project page into the global wiki (with redaction)
+    lint <project>           Run wiki-lint checks on State/
+
+  Global wiki:
+    wiki                     Resolve + scaffold + open the global wiki (one-shot)
+    global init|status|ask|lint|show-root|set-root|migrate
+
+  Install / lifecycle:
+    upgrade                  npm i -g kushi-agents@latest then re-seed assets in cwd
+    uninstall [--keep-config]  Remove <cwd>/.kushi/ (preserves Evidence/, State/)
+    doctor                   Aggregated health check (env, drift, evals, etc.)
+    --version | -v           Print kushi version and exit
+    help | --help            Show this help
+
+  Skill authoring (full profile):
+    create-skill <name>      Scaffold a new plugin/skills/<name>/ tree
+    check-skill <name>       Lint a skill against the blueprint
+    optimize-description <s> Rewrite a skill's description per optimizer rules
+    review-evals <skill>     Render an HTML eval-review viewer
+    explain <topic>          Explain a kushi concept (read-only)
+    remember <rule>          Persist a project convention to CLAUDE.md
+    hooks list|test <project>  Inspect or fire hook events
+
+Chat Verbs (run from VS Code Copilot Chat with @Kushi <verb>):
+    @Kushi ask <project> <q>          Cited Q&A over Evidence/ (auto-routes)
+    @Kushi status <project>           Run-log + freshness summary
+    @Kushi consolidate <project>      Merge per-user evidence into _Consolidated
+    @Kushi tour <project> [--top N]   Auto-generated week-in-review walkthrough
+    @Kushi dashboard <project>        Status dashboard
+    @Kushi aggregate <project>        Multi-week aggregate
+    @Kushi fde-intake | fde-report | fde-triage <project>
+    @Kushi link-entities <project>    Cross-link entities across projects
+    @Kushi teach <topic>              Teach kushi a doctrine fact
+    @Kushi explain <topic>            Recall a taught fact
+    @Kushi vertex-link | emit-vertex <project>
+
+  These verbs need the LLM-driven orchestrator that only Copilot Chat
+  provides (interactive clarifications + cited narrative). Typing them in
+  the shell prints a redirect to the chat path.
 
 Install (run via npx — first-time / host install):
   npx kushi-agents --clawpilot     Install to ~/.copilot/m-skills/kushi/
@@ -276,6 +361,7 @@ Install (run via npx — first-time / host install):
   WorkIQ:    --with-workiq | --workiq-path <abs> | --skip-workiq-check
 
 Run 'kushi <command> --help' for more information on a command (where supported).
+Run 'kushi --version' to print the installed version.
 Docs: https://gim-home.github.io/kushi/
 
 In VS Code Chat the prefix is "@Kushi". In Clawpilot just say "kushi <verb>".
@@ -283,10 +369,12 @@ In VS Code Chat the prefix is "@Kushi". In Clawpilot just say "kushi <verb>".
 }
 
 
-// ── state / refresh / bootstrap verbs (v5.9.0+) ─────────────────────────────
-// Thin shells that exec the deterministic runners. Keeps `kushi state HCA` etc.
-// runnable from the global bin without users having to know the runner paths.
-if (args.length > 0 && ['state', 'refresh-runner', 'bootstrap-runner', 'discover', 'references'].includes(args[0])) {
+// ── deterministic runner verbs (v5.9.0+, renamed in v5.9.6) ─────────────────
+// Thin shells that exec the deterministic runners. `kushi refresh HCA` /
+// `kushi bootstrap HCA` / `kushi state HCA` etc. all run from the global bin
+// without users having to know the runner paths. Chat orchestrator
+// `@Kushi refresh` adds narrative + interactive clarification on top.
+if (args.length > 0 && ['state', 'refresh', 'bootstrap', 'discover', 'references'].includes(args[0])) {
   const verb = args[0];
   const project = args[1];
   if (!project) {
@@ -298,15 +386,29 @@ if (args.length > 0 && ['state', 'refresh-runner', 'bootstrap-runner', 'discover
   const urlMod = await import('node:url');
   const here = pathMod.dirname(urlMod.fileURLToPath(import.meta.url));
   const runnerMap = {
-    state: 'pull-state.mjs',
+    state:      'pull-state.mjs',
     references: 'pull-references.mjs',
-    discover: 'discover.mjs',
-    'refresh-runner': 'refresh.mjs',
-    'bootstrap-runner': 'bootstrap.mjs',
+    discover:   'discover.mjs',
+    refresh:    'refresh.mjs',
+    bootstrap:  'bootstrap.mjs',
   };
   const runner = pathMod.resolve(here, '..', 'plugin', 'runners', runnerMap[verb]);
   const passthrough = args.slice(2);
-  const r = spawnSync(process.execPath, [runner, '--project', project, ...passthrough], { stdio: 'inherit' });
+  // v5.9.7: resolve alias the same way chat does, unless caller already passed --alias
+  const hasAliasFlag = passthrough.some((a, i) => a === '--alias' && passthrough[i + 1]);
+  let aliasArgs = [];
+  if (!hasAliasFlag) {
+    const { alias, source } = await resolveAlias();
+    if (!alias) {
+      printAliasError(verb, project);
+      process.exit(1);
+    }
+    aliasArgs = ['--alias', alias];
+    if (source === 'env') {
+      process.stderr.write(`\n  Using alias='${alias}' from KUSHI_ALIAS env var.\n`);
+    }
+  }
+  const r = spawnSync(process.execPath, [runner, '--project', project, ...aliasArgs, ...passthrough], { stdio: 'inherit' });
   process.exit(r.status ?? 1);
 }
 
@@ -338,12 +440,43 @@ if (args.length > 0 && args[0] === 'uninstall' && !args.includes('--clawpilot')
 
 if (args.length > 0 && args[0] === 'upgrade') {
   // Upgrade: npm i -g @latest, then re-seed assets in cwd preserving config.
+  // v5.9.5: capture stderr so users see WHY npm failed; detect Windows
+  // self-replacement (kushi.cmd locked because it's the running shell) and
+  // print a clear "rerun from a fresh shell" hint.
   const { spawnSync } = await import('node:child_process');
   console.log('\n  Upgrading kushi-agents globally via npm...\n');
   const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-  const r1 = spawnSync(npm, ['install', '-g', 'kushi-agents@latest'], { stdio: 'inherit' });
+  const r1 = spawnSync(npm, ['install', '-g', 'kushi-agents@latest'], {
+    stdio: ['inherit', 'inherit', 'pipe'],
+    encoding: 'utf-8',
+  });
   if (r1.status !== 0) {
-    console.error('\n  npm install failed.\n');
+    const stderr = (r1.stderr || '').toString();
+    if (stderr) {
+      console.error(stderr);
+    }
+    const looksLikeSelfReplace = process.platform === 'win32' && (
+      /EPERM|EBUSY|operation not permitted|kushi\.cmd|kushi-agents\.cmd|in use/i.test(stderr)
+    );
+    if (looksLikeSelfReplace) {
+      console.error([
+        '',
+        '  npm could not overwrite the running kushi.cmd shim.',
+        '  This is a known Windows limitation when `kushi upgrade` is launched from kushi itself.',
+        '',
+        '  Fix: open a NEW PowerShell window and run:',
+        '',
+        '      npm i -g kushi-agents@latest',
+        '',
+        '  Then re-seed your workspace:',
+        '',
+        '      cd ' + process.cwd(),
+        '      npx kushi-agents@latest --force',
+        '',
+      ].join('\n'));
+    } else if (!stderr) {
+      console.error('\n  npm install failed (no stderr captured). Try:\n      npm i -g kushi-agents@latest --foreground-scripts --loglevel=verbose\n');
+    }
     process.exit(r1.status ?? 1);
   }
   console.log('\n  Refreshing assets in cwd (config preserved)...\n');
@@ -361,10 +494,12 @@ if (args.length > 0 && args[0] === 'upgrade') {
 // These verbs are dispatched by Copilot Chat (`@Kushi <verb>`), not the CLI.
 // If a user types e.g. `kushi ask HCA "..."` in PowerShell, fall through to
 // installer used to silently run. Now we print a friendly redirect.
+// v5.9.6: refresh/bootstrap removed — they now route to the deterministic
+// runners directly (see runner-verbs block above).
 const CHAT_ONLY_VERBS = new Set([
-  'ask', 'bootstrap', 'refresh', 'status', 'consolidate', 'tour', 'dashboard',
+  'ask', 'status', 'consolidate', 'tour', 'dashboard',
   'aggregate', 'fde-intake', 'fde-report', 'fde-triage', 'link-entities',
-  'migrate-files', 'pull', 'schema-evolve', 'teach', 'vertex-link',
+  'migrate-files', 'schema-evolve', 'teach', 'vertex-link',
   'emit-vertex',
 ]);
 if (args.length > 0 && CHAT_ONLY_VERBS.has(args[0])) {
@@ -379,9 +514,11 @@ if (args.length > 0 && CHAT_ONLY_VERBS.has(args[0])) {
   In Clawpilot:
       kushi ${verb}${rest ? ' ' + rest : ' <project> [args]'}
 
-  CLI verbs (run from PowerShell): kushi help, kushi wiki, kushi doctor,
-                                   kushi upgrade, kushi uninstall, kushi setup,
-                                   kushi state, kushi promote, kushi global, kushi lint
+  CLI verbs (deterministic, run from PowerShell):
+      kushi bootstrap | refresh | state | references | discover <project>
+      kushi promote | lint <project>
+      kushi wiki | global | doctor | upgrade | uninstall | setup
+      kushi help | --version
   See:  kushi help
 `);
   process.exit(2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "5.9.4",
+  "version": "5.9.7",
   "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": {

package/plugin/agents/kushi.agent.md

@@ -103,6 +103,9 @@ When a user message arrives:
 
 1. Identify the **verb** (setup / aggregate / bootstrap / refresh / state / consolidate / status / pull / **ask** / fde-intake / fde-report / fde-triage).
    - If the message starts with an explicit producer verb → use it.
+   - **Natural-language verb synonyms** auto-route to canonical verbs:
+     - "update <X>" / "pull <X>" / "sync <X>" / "regenerate <X>" / "do it all for <X>" / "weekly extract for <X>" / "bring <X> up to date" → `refresh <X>`
+     - "init <X>" / "new <X>" / "set up project evidence for <X>" / "add me to project <X>" / "add contributor to <X>" → `bootstrap <X>`
    - **setup** dispatches immediately on `setup`, `setup --reconfigure`, `verify workiq`, `who am I to kushi`, `fix my install`, `setup kushi`.
    - Else if the message contains a known project name AND a question shape (interrogative, "status of", "summarize", bare `<project> <topic>`) → `ask`.
    - Else → ask the user to clarify.