kushi-agents 4.1.0 → 4.2.2

package/bin/cli.mjs

@@ -29,6 +29,13 @@ if (args.includes('--help') || args.includes('-h')) {
                         check (useful for scripted or agent-driven installs)
     --no-settings       Skip .vscode/settings.json update (vscode target only)
     --no-instructions   Skip .github/copilot-instructions.md merge (vscode target only)
+
+  WorkIQ (REQUIRED — Kushi cannot pull evidence without it):
+    --with-workiq           Auto-install WorkIQ via winget (Windows) / brew (macOS)
+    --workiq-path <abs>     Use this explicit path to the workiq binary
+    --skip-workiq-check     Bypass the WorkIQ pre-flight check (CI / inspection only —
+                            bootstrap/refresh will block until WorkIQ is installed)
+
     --help, -h          Show this help
 
   After install, talk to Kushi:
@@ -62,6 +69,9 @@ const options = {
   noInstructions: args.includes('--no-instructions'),
   target,
   profile: getFlag('--profile'),
+  withWorkiq: args.includes('--with-workiq'),
+  workiqPath: getFlag('--workiq-path'),
+  skipWorkiqCheck: args.includes('--skip-workiq-check'),
 };
 
 main(options).catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "4.1.0",
+  "version": "4.2.2",
   "description": "Install Kushi — multi-source project evidence agent with snapshot+stream capture across Email, Teams, OneNote, SharePoint, Meetings, CRM, ADO. WorkIQ-only for M365 sources (Graph / m365_* FORBIDDEN as fallbacks; user-paste is first-class). Host-agnostic.",
   "type": "module",
   "bin": {
@@ -42,6 +42,11 @@
     "url": "https://github.com/gim-home/kushi/issues"
   },
   "license": "MIT",
+  "scripts": {
+    "test": "node --test src/check-workiq.test.mjs",
+    "smoke": "node scripts/smoke.mjs",
+    "prepublishOnly": "npm test && npm run smoke"
+  },
   "publishConfig": {
     "access": "public"
   }

package/plugin/instructions/identity-resolution.instructions.md

@@ -0,0 +1,66 @@
+---
+applyTo: "**"
+description: "Identity auto-resolution — Kushi never asks the user for alias / email / display_name. On the first bootstrap (or whenever those fields are <auto> / placeholder in .kushi/config/project-evidence.yml), Kushi resolves them from WorkIQ in a single call, persists them, and continues. Skipped entirely if the user has set explicit values."
+---
+
+# Identity Resolution — Don't Ask, Probe
+
+Kushi must not prompt the user for `alias`, `email`, or `display_name`. These are derivable from WorkIQ in one call, and asking is poor UX.
+
+## When to resolve
+
+On the **first step of every prompt** that reads contributor identity (bootstrap, refresh, aggregate, ask, fde-*, propose-ado, apply-ado), check `<workspace>/.kushi/config/project-evidence.yml`:
+
+* If `alias`, `email`, or `display_name` is **missing**, set to `<auto>`, or matches a placeholder pattern (`<your-alias>`, `<Your Full Name>`, `your.email@example.com`) → **resolve from WorkIQ**.
+* If all three are explicit non-placeholder values → **skip**. Respect the user's override.
+
+## How to resolve
+
+Single WorkIQ call:
+
+```bash
+workiq ask -q "Who am I? Return my UPN (email), display name, and mail nickname as JSON: {\"upn\":\"...\",\"displayName\":\"...\",\"mailNickname\":\"...\"}"
+```
+
+Map the response:
+
+| Config field   | Source                              | Fallback if missing                  |
+|----------------|-------------------------------------|--------------------------------------|
+| `email`        | `upn`                               | Block — must be present              |
+| `display_name` | `displayName`                       | Same as `alias`                      |
+| `alias`        | `mailNickname`                      | `upn.split('@')[0]` (lowercase)      |
+
+## After resolution
+
+1. **Persist back** to `<workspace>/.kushi/config/project-evidence.yml` (preserving comments + indentation). The user sees the resolved values on next open; no surprise.
+2. **Echo back** to the user, one line:
+   > ✓ Identity: `Alex Smith <alex@microsoft.com>` (alias=`alex`). Edit `.kushi/config/project-evidence.yml` to override.
+3. **Continue** the prompt.
+
+## Failure modes
+
+| Scenario                                      | Behavior                                                                                                                     |
+|-----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
+| WorkIQ returns auth error                     | Block: "Sign in to WorkIQ first: `workiq accept-eula && workiq ask -q ping`". Do not proceed.                                |
+| WorkIQ returns empty / NO_RESULTS             | Block: "WorkIQ could not resolve your identity. Try `workiq ask -q 'who am I'` and retry."                                   |
+| WorkIQ binary missing                         | This should already have been caught by the installer's pre-flight. If reached, block with the same install hint.            |
+| User has explicit non-placeholder values      | Skip resolution entirely. Never overwrite user-set values.                                                                   |
+| Alias collision with another contributor      | Bootstrap detects existing `Evidence/<alias>/` whose `contributors.yml` records a different email → ask the user to disambiguate (suggest `<alias>-<tenant-prefix>` e.g. `alex-ms`). |
+
+## What NOT to do
+
+* Do NOT ask the user `What alias should Kushi use?`. The legacy onboarding prompt is gone.
+* Do NOT call `m365_*` / Graph as a fallback. WorkIQ is the single source of identity truth (`workiq-first.instructions.md`).
+* Do NOT resolve on every run. Once persisted, the config values are authoritative.
+
+## Integration with other doctrine
+
+* `workiq-first.instructions.md` — identity resolution is the canonical example of WorkIQ-first. Add to the inventory.
+* `bootstrap-project` SKILL — Step 0 is identity resolution. Step 1 is project context.
+* `tracking.instructions.md` — the resolved identity goes into the tracking artifact's frontmatter under `actor:`.
+
+## References
+
+* `workiq-first.instructions.md` — the parent doctrine.
+* `engagement-root-resolution.instructions.md` — `projects_root` resolution (separate from identity).
+* `templates/init/project-evidence.template.yml` — defaults to `<auto>` for these three fields.

package/plugin/instructions/workiq-only.instructions.md

@@ -28,6 +28,7 @@ Applies to ALL evidence retrieval from these M365 sources:
 - Email bodies and attachments
 - SharePoint file contents (when text extraction is needed)
 - Calendar events (when not already known by id)
+- **Contributor identity** (UPN / displayName / mailNickname) — see `identity-resolution.instructions.md` for the canonical "who am I?" probe.
 
 **Out of scope** (these are NOT WorkIQ — they remain on their direct paths):
 

package/plugin/skills/bootstrap-project/SKILL.md

@@ -35,10 +35,25 @@ After every run (success or coverage-gaps), write `<project>/bootstrap-status.md
 
 - `<project>` — engagement name (fuzzy-matched per `engagement-root-resolution.instructions.md`).
 - `<window>` — defaults to **last 30 days** (override with `last N days` / `since <date>`).
-- Implicit: current contributor `<alias>` (from personal config).
+- Implicit: current contributor `<alias>` (resolved in Step 0 — see below).
 
 ## Steps
 
+### Step 0 — Identity resolution (REQUIRED, never asks the user)
+
+Per `identity-resolution.instructions.md`. Read `<workspace>/.kushi/config/project-evidence.yml`:
+
+* If `alias`, `email`, or `display_name` is missing / `<auto>` / matches a placeholder → call WorkIQ once:
+  ```
+  workiq ask -q "Who am I? Return UPN, displayName, mailNickname as JSON."
+  ```
+  Map `upn → email`, `displayName → display_name`, `mailNickname → alias` (fallback `email.split('@')[0]`).
+* Persist resolved values back to the YAML (preserve comments).
+* Echo one line: `✓ Identity: <displayName> <<UPN>> (alias=<alias>). Edit .kushi/config/project-evidence.yml to override.`
+* If all three are already explicit non-placeholder values → skip silently.
+
+Hard stop if WorkIQ returns auth error or empty — print the WorkIQ sign-in hint and exit. Never fall back to asking the user.
+
 ### Step 1 — Machine preflight (SETUP)
 
 Verify in order. Stop on hard failures.

package/plugin/templates/init/project-evidence.template.yml

@@ -5,14 +5,23 @@
 # maintains their own. Nothing here is a secret, but it IS personal —
 # add `.kushi/config/` to .gitignore before committing the rest of .kushi/.
 #
-# Edit the values below (lines marked FILL ME IN), then run `bootstrap <project>`.
+# IDENTITY — auto-detected on first bootstrap.
+#   On the first run of `bootstrap <project>`, Kushi asks WorkIQ "who am I?"
+#   and fills these three fields in for you (UPN, displayName, mailNickname).
+#   You only need to override them if you want a different folder name or
+#   a friendlier display label. Leave them at the placeholder values to
+#   trigger auto-detection.
 
-# FILL ME IN — short id used as your evidence subfolder name (e.g. "alex", "jordan").
-alias: <your-alias>
+# Optional override — short id used as your Evidence/ subfolder name.
+# Leave as <auto> to derive from the part before "@" in your email.
+alias: <auto>
 
-# FILL ME IN
-display_name: <Your Full Name>
-email: your.email@example.com
+# Optional override — friendly label used in run logs.
+# Leave as <auto> to pull from WorkIQ's displayName.
+display_name: <auto>
+
+# Optional override — your work email. Leave as <auto> to pull from WorkIQ.
+email: <auto>
 
 # FILL ME IN — where your engagement-root lives. The parent folder containing
 # one subfolder per project (typically synced from a team SharePoint library).
@@ -35,4 +44,5 @@ active_projects:
 #   2. `workiq` on PATH
 #   3. ~/.kushi/bin/workiq.cmd  (Windows) / ~/.kushi/bin/workiq  (Linux/macOS)
 # workiq:
-#   cli_path: 'C:\Users\<you>\.kushi\bin\workiq.cmd'
+#   cli_path: 'C:\Users\<you>\.kushi\bin\workiq.cmd'
+

package/src/check-workiq.mjs

@@ -0,0 +1,145 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+/**
+ * Probe for a working WorkIQ install.
+ *
+ * Resolution order:
+ *   1. explicit absolute path supplied via --workiq-path / opts.workiqPath
+ *   2. `workiq` on PATH (via `where` on Windows, `command -v` elsewhere)
+ *   3. Kushi-managed bin: ~/.kushi/bin/workiq.cmd (Win) or ~/.kushi/bin/workiq
+ *
+ * Returns:
+ *   { ok: true,  path, version }                       — usable WorkIQ found
+ *   { ok: false, reason, hint }                        — not found / not runnable
+ *
+ * Reasons:
+ *   'not-found'        — no workiq binary anywhere we looked
+ *   'path-invalid'     — explicit --workiq-path was given but the file doesn't exist
+ *   'not-executable'   — found but `--version` failed (corrupt install, missing deps, etc.)
+ */
+export function checkWorkIQ(opts = {}) {
+  const isWin = process.platform === 'win32';
+  const homeBin = path.join(
+    os.homedir(),
+    '.kushi',
+    'bin',
+    isWin ? 'workiq.cmd' : 'workiq',
+  );
+
+  if (opts.workiqPath) {
+    const abs = path.resolve(opts.workiqPath);
+    if (!existsSync(abs) || !statSync(abs).isFile()) {
+      return {
+        ok: false,
+        reason: 'path-invalid',
+        hint: `--workiq-path "${opts.workiqPath}" does not point at an existing file.`,
+      };
+    }
+    return runVersion(abs);
+  }
+
+  const onPath = findOnPath('workiq');
+  if (onPath) return runVersion(onPath);
+
+  if (existsSync(homeBin) && statSync(homeBin).isFile()) {
+    return runVersion(homeBin);
+  }
+
+  return {
+    ok: false,
+    reason: 'not-found',
+    hint: installHint(),
+  };
+}
+
+function findOnPath(name) {
+  const isWin = process.platform === 'win32';
+  const cmd = isWin ? 'where' : 'command';
+  const args = isWin ? [name] : ['-v', name];
+  const res = spawnSync(cmd, args, { encoding: 'utf-8', shell: !isWin });
+  if (res.status !== 0) return null;
+  const all = (res.stdout || '')
+    .split(/\r?\n/)
+    .map((s) => s.trim())
+    .filter(Boolean);
+  if (!isWin) return all[0] || null;
+  // Windows `where` may return multiple matches (e.g. npm shims produce both
+  // `workiq` (bash script, no extension) and `workiq.cmd`). Prefer
+  // executable extensions in priority order; fall back to the first match.
+  const priority = ['.cmd', '.exe', '.bat', '.ps1'];
+  for (const ext of priority) {
+    const hit = all.find((p) => p.toLowerCase().endsWith(ext));
+    if (hit) return hit;
+  }
+  return all[0] || null;
+}
+
+function runVersion(binPath) {
+  // Windows requires shell:true to spawn .cmd / .bat / shim files. The DEP0190
+  // warning is harmless here because we control both binPath (resolved via
+  // `where` / explicit --workiq-path) and args (literal ['--version']).
+  const isWin = process.platform === 'win32';
+  const res = spawnSync(binPath, ['--version'], {
+    encoding: 'utf-8',
+    timeout: 10_000,
+    shell: isWin,
+  });
+  if (res.status !== 0) {
+    return {
+      ok: false,
+      reason: 'not-executable',
+      hint: `Found WorkIQ at ${binPath} but \`workiq --version\` failed (exit ${res.status}). Try reinstalling. ${installHint()}`,
+    };
+  }
+  const version = (res.stdout || res.stderr || '').trim().split(/\r?\n/)[0] || 'unknown';
+  return { ok: true, path: binPath, version };
+}
+
+function installHint() {
+  const plat = process.platform;
+  if (plat === 'win32') {
+    return 'Install with: winget install Microsoft.WorkIQ';
+  }
+  if (plat === 'darwin') {
+    return 'Install with: brew install --cask microsoft-workiq';
+  }
+  return 'See https://gim-home.github.io/kushi/getting-started/install-workiq/ for Linux instructions.';
+}
+
+/**
+ * Best-effort auto-install via the platform's package manager.
+ * Only invoked when --with-workiq is passed. Non-blocking on failure —
+ * caller decides whether to hard-fail.
+ *
+ * Returns { ok, reason, output }.
+ */
+export function tryInstallWorkIQ() {
+  const plat = process.platform;
+  let cmd, args;
+  if (plat === 'win32') {
+    cmd = 'winget';
+    args = ['install', '--id', 'Microsoft.WorkIQ', '-e', '--accept-package-agreements', '--accept-source-agreements'];
+  } else if (plat === 'darwin') {
+    cmd = 'brew';
+    args = ['install', '--cask', 'microsoft-workiq'];
+  } else {
+    return {
+      ok: false,
+      reason: 'unsupported-platform',
+      output: 'Auto-install is not supported on Linux. See https://gim-home.github.io/kushi/getting-started/install-workiq/',
+    };
+  }
+
+  const res = spawnSync(cmd, args, { encoding: 'utf-8', stdio: 'inherit' });
+  if (res.error || res.status !== 0) {
+    return {
+      ok: false,
+      reason: 'install-failed',
+      output: res.error ? res.error.message : `${cmd} exited with status ${res.status}`,
+    };
+  }
+  return { ok: true, output: `${cmd} ${args.join(' ')} succeeded` };
+}

package/src/check-workiq.test.mjs

@@ -0,0 +1,93 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import os from 'node:os';
+import fs from 'node:fs';
+
+import { checkWorkIQ } from './check-workiq.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const isWin = process.platform === 'win32';
+
+function makeTempBin(name, body) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'kushi-test-'));
+  const full = path.join(dir, name);
+  fs.writeFileSync(full, body);
+  if (!isWin) fs.chmodSync(full, 0o755);
+  return { dir, full };
+}
+
+test('checkWorkIQ: --workiq-path pointing at non-existent file returns path-invalid', () => {
+  const r = checkWorkIQ({ workiqPath: '/definitely/does/not/exist/workiq' });
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'path-invalid');
+  assert.match(r.hint, /does not point at an existing file/i);
+});
+
+test('checkWorkIQ: --workiq-path pointing at a runnable script returns ok with version', () => {
+  // Build a tiny fake that prints a version string and exits 0.
+  const name = isWin ? 'fake-workiq.cmd' : 'fake-workiq';
+  const body = isWin
+    ? '@echo off\r\necho 9.9.9-fake\r\nexit /b 0\r\n'
+    : '#!/usr/bin/env bash\necho 9.9.9-fake\nexit 0\n';
+  const { full, dir } = makeTempBin(name, body);
+  try {
+    const r = checkWorkIQ({ workiqPath: full });
+    assert.equal(r.ok, true, `expected ok, got ${JSON.stringify(r)}`);
+    assert.equal(r.path, full);
+    assert.match(r.version, /9\.9\.9-fake/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('checkWorkIQ: --workiq-path pointing at a failing binary returns not-executable', () => {
+  const name = isWin ? 'broken-workiq.cmd' : 'broken-workiq';
+  const body = isWin
+    ? '@echo off\r\nexit /b 17\r\n'
+    : '#!/usr/bin/env bash\nexit 17\n';
+  const { full, dir } = makeTempBin(name, body);
+  try {
+    const r = checkWorkIQ({ workiqPath: full });
+    assert.equal(r.ok, false);
+    assert.equal(r.reason, 'not-executable');
+    assert.match(r.hint, /failed/i);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('checkWorkIQ: with no PATH match and no override returns not-found with platform hint', () => {
+  const savedPath = process.env.PATH;
+  const savedPathCap = process.env.Path;
+  const savedHome = process.env.HOME;
+  const savedProfile = process.env.USERPROFILE;
+  try {
+    const fakeRoot = path.join(os.tmpdir(), `kushi-empty-${Date.now()}`);
+    process.env.PATH = fakeRoot;
+    if (isWin) process.env.Path = fakeRoot;
+    process.env.HOME = fakeRoot;
+    if (isWin) process.env.USERPROFILE = fakeRoot;
+
+    const r = checkWorkIQ();
+    assert.equal(r.ok, false);
+    assert.equal(r.reason, 'not-found');
+    if (isWin) {
+      assert.match(r.hint, /winget install Microsoft\.WorkIQ/);
+    } else if (process.platform === 'darwin') {
+      assert.match(r.hint, /brew install --cask microsoft-workiq/);
+    } else {
+      assert.match(r.hint, /install-workiq/);
+    }
+  } finally {
+    process.env.PATH = savedPath;
+    if (savedPathCap !== undefined) process.env.Path = savedPathCap;
+    else delete process.env.Path;
+    if (savedHome !== undefined) process.env.HOME = savedHome;
+    else delete process.env.HOME;
+    if (savedProfile !== undefined) process.env.USERPROFILE = savedProfile;
+    else delete process.env.USERPROFILE;
+  }
+});

package/src/main.mjs

@@ -17,6 +17,7 @@ import { copyAssets, copyProjectFiles } from './copy-assets.mjs';
 import { mergeSettings } from './settings.mjs';
 import { mergeCopilotInstructions } from './copilot-instructions.mjs';
 import { seedConfig } from './seed-config.mjs';
+import { checkWorkIQ, tryInstallWorkIQ } from './check-workiq.mjs';
 import {
   resolveProfile,
   makeIncludeFilter,
@@ -71,6 +72,9 @@ export async function main(options = {}) {
   console.log(`  Profile chain: ${resolved.chain.join(' -> ')}`);
   console.log(`  ${resolved.description}\n`);
 
+  // Hard prerequisite: WorkIQ. Kushi cannot pull evidence without it.
+  await preflightWorkIQ(options);
+
   if (target === TARGET_CLAWPILOT) {
     await installClawpilot(options, resolved, version);
   } else {
@@ -290,6 +294,56 @@ async function confirmOverwriteIfExists(fullDest, displayDest, force) {
   }
 }
 
+/**
+ * Hard prerequisite: WorkIQ must be installed and runnable before Kushi will
+ * copy any assets. Kushi's pull-* skills are useless without it. Three modes:
+ *
+ *   --skip-workiq-check  → print a warning and continue (CI / asset-inspection only)
+ *   --with-workiq        → attempt auto-install via winget/brew first, then re-check
+ *   default              → probe; on failure, print install hint and exit 1
+ *
+ * Always prints the resolved WorkIQ path + version on success so users have a
+ * record in their terminal scrollback.
+ */
+async function preflightWorkIQ(options) {
+  if (options.skipWorkiqCheck) {
+    console.warn(
+      '  ⚠️  WorkIQ pre-flight skipped (--skip-workiq-check).',
+    );
+    console.warn(
+      '      Kushi will install, but bootstrap/refresh will block until WorkIQ is present.\n',
+    );
+    return;
+  }
+
+  let result = checkWorkIQ({ workiqPath: options.workiqPath });
+
+  if (!result.ok && options.withWorkiq) {
+    console.log('  WorkIQ not found — attempting auto-install (--with-workiq)…\n');
+    const ins = tryInstallWorkIQ();
+    if (!ins.ok) {
+      console.error(`\n  ✖ Auto-install failed: ${ins.output}\n`);
+      console.error(`    ${result.hint || ''}\n`);
+      process.exit(1);
+    }
+    result = checkWorkIQ({ workiqPath: options.workiqPath });
+  }
+
+  if (!result.ok) {
+    console.error('\n  ✖ WorkIQ is required and was not found.\n');
+    console.error('    Kushi cannot capture evidence without WorkIQ. Install it first:\n');
+    console.error(`      ${result.hint}\n`);
+    console.error('    Then run `workiq ask -q "ping"` to confirm sign-in, and re-run this installer.\n');
+    console.error('    Escape hatches (NOT recommended):');
+    console.error('      • --workiq-path <abs>     supply a non-standard install path');
+    console.error('      • --with-workiq           let the installer try winget/brew');
+    console.error('      • --skip-workiq-check     install assets anyway (bootstrap will still block)\n');
+    process.exit(1);
+  }
+
+  console.log(`  ✓ WorkIQ detected at ${result.path} (${result.version})\n`);
+}
+
 /**
  * Detect whether the cwd looks like a sane install target and, if not, print
  * an actionable message. Three cases: