kushi-agents 5.7.1 → 5.7.2

package/README.md

@@ -260,6 +260,7 @@ npx kushi-agents --clawpilot                       # Clawpilot only
 npx kushi-agents --vscode                          # VS Code Chat only
 
 # Install to BOTH at once (auto-detects what's present + targets both)
+# v5.7.1+: when run from inside a project dir, also refreshes <cwd>/.kushi/.
 npx kushi-agents --all-hosts
 
 # Uninstall

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "5.7.1",
+  "version": "5.7.2",
   "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": {
@@ -43,7 +43,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 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 src/doctor.test.mjs src/setup-wizard.test.mjs src/cli-no-args.test.mjs src/cli-no-args-tty.test.mjs src/per-user-files.test.mjs src/layout-portable.test.mjs src/profile-coverage.test.mjs plugin/runners/test/unit/*.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 src/doctor.test.mjs src/setup-wizard.test.mjs src/cli-no-args.test.mjs src/cli-no-args-tty.test.mjs src/per-user-files.test.mjs src/layout-portable.test.mjs src/profile-coverage.test.mjs src/get-kushi-config.test.mjs plugin/runners/test/unit/*.test.mjs",
     "test:runners": "node --test plugin/runners/test/unit/*.test.mjs",
     "test:runners:integration": "node --test plugin/runners/test/integration/*.test.mjs",
     "test:integration:bootstrap": "node src/bootstrap-dryrun.integration.test.mjs",

package/plugin/learnings/cross-cutting.md

@@ -4,6 +4,65 @@ Newest on top. Format defined in [`README.md`](./README.md). Use this file when
 
 ---
 
+### 2026-05-29 — `[switch]` parameter collides with same-name local var in PowerShell
+
+**Symptom**: Calling `.\.kushi\lib\Get-KushiConfig.ps1 -Name 'm365-auth' -Raw` threw at the **call site**:
+
+```
+Get-KushiConfig.ps1: Cannot convert the "{ ...full file contents... }" value of type "System.String" to type "System.Management.Automation.SwitchParameter".
+```
+
+The error wrapped the entire file content as the failed-coercion value — confusing, because the user's invocation only passed `-Name '...' -Raw` (no positional value).
+
+**Root cause**: PowerShell variables are **case-insensitive**. The script declared `[switch] $Raw` as a parameter, then used a local `$raw = Get-Content -LiteralPath $resolved -Raw` to read the file. Those are the *same variable*. The string assignment to the typed switch parameter triggered SwitchParameter coercion, which fails on any non-empty string. Crucially, the error is reported at the *call site* (the `&` invocation line), not at the assignment line — so the symptom looked like a parameter-binding bug.
+
+**Fix shipped (v5.7.2, 2026-05-29)**: Renamed the local var to `$rawText` everywhere in `Get-KushiConfig.ps1`. Audited all other `[switch]` params in `plugin/lib/*.ps1` for the same collision pattern — none found.
+
+**Why it wasn't caught**: 280 unit tests cover only `.mjs` runners. `Get-KushiConfig.ps1` and other shipped `.ps1` libs had **zero** automated test coverage. Added `src/get-kushi-config.test.mjs` (3 tests) that installs kushi into a temp dir and invokes the live shipped script via `pwsh`, asserting no SwitchParameter coercion error in stderr. Now wired into `npm test` (283 tests).
+
+**Lesson**: Any `.ps1` file shipped to users needs *integration* tests that invoke the real script via `pwsh`, not just unit tests of the JS that calls it. Avoid using `[switch]` parameter names that collide with common local variable names (`$raw`, `$path`, `$name`, `$content`) — PS case-insensitivity makes the collision invisible until something assigns a value.
+
+---
+
+### 2026-05-29 — Two issues that silently broke `bootstrap` end-to-end on Windows
+
+**Symptom**: After v5.7.0 shipped the auto-chain (bootstrap → discover → refresh), users ran the chain on Windows and saw discover return `skipped_reason: EINVAL` for every source, then refresh exit 0 with zero pulls. The runner *appeared* to be working — `status: ok`, no error message — but no boundaries were filled.
+
+**Root causes** (two stacked):
+
+1. **Node 20.12+ refuses to spawn `.cmd`/`.bat` files without `shell:true`** (CVE-2024-27980 hardening). `lib/workiq.mjs` was using `spawn(exe, args, { shell: false })` and the Windows workiq distribution ships as a `workiq.cmd` shim. Every spawn returned `EINVAL` immediately. The runner caught it and recorded `skipped_reason: EINVAL` per-source, but didn't escalate — it looked like 7 individual source-not-available skips, not one runtime-level failure.
+2. **`resolveWorkiqBin()` only checked `~/.copilot/bin/workiq.cmd`**. Users who installed WorkIQ via `npm i -g @microsoft/workiq` had it at `C:\Users\<u>\AppData\Roaming\npm\workiq.cmd` — invisible to kushi, even though `workiq --version` worked fine in their shell.
+
+**Fixes shipped (v5.7.1, 2026-05-29)**:
+
+1. **`lib/workiq.mjs` `runProcess()` routes `.cmd`/`.bat` through `cmd.exe`** with `windowsVerbatimArguments: true`. Verbatim args preserve quoting in long CSC prompts.
+2. **`resolveWorkiqBin()` searches PATH first** (with `PATHEXT`-aware `whichSync`), falls back to `~/.copilot/bin/`. So `npm`-installed workiq is now picked up automatically.
+3. **Lesson for future runners**: a per-source `skipped_reason` in JSON output isn't a substitute for a top-level error. If every source returns the SAME error code, that's a runtime failure, not 7 missing-source signals. Consider adding a `runtime_error` envelope check in discover that flips the top-level `status` to `error` if ≥N sources skip with the same `EXXX` code.
+
+**Discovered during**: Soak test of v5.7.0 in `kushi-wp` workspace — discover printed `{"status":"ok",...}` with all 7 sources `skipped_reason: EINVAL`, refresh ran clean, but no boundary was actually filled. Symptom looked like "WorkIQ has nothing for this project" until the user ran `node -e "spawn(...)"` to repro the EINVAL.
+
+---
+
+### 2026-05-29 — Two-command install (`--all-hosts` then workspace) is the wrong default
+
+**Symptom**: User runs:
+
+```
+npx kushi-agents@latest --all-hosts --profile full
+cd <repo-root>-wp
+npx kushi-agents@latest --profile full
+```
+
+…and asks: *"this is weird running both. is there a better way?"*
+
+**Root cause**: The CLI dispatched on the presence of host flags. `--all-hosts` took the `runMultiHost()` code path which did host-only installs. `npx kushi-agents` (no flag) took the legacy `main.mjs` workspace-install path. The two paths were mutually exclusive, even though the user's mental model was *"install Kushi everywhere"* — both globally and in the current repo.
+
+**Fix shipped (v5.7.1)**: After the host loop in `runMultiHost()`, detect if cwd is a recognized project (uses the existing `findProjectMarker()` from `main.mjs` — `.git`, `package.json`, `.kushi/`, `Evidence/`, etc.). If yes, also call `main({ target: 'vscode', yes: true, force: true })` to refresh the workspace install. Suppress with `--no-workspace`. From a non-project directory, prints `Workspace install skipped` and only does host install.
+
+**Result**: `npx kushi-agents@latest --all-hosts --profile full` from inside a repo now does the entire install in one shot. Help text + `docs/getting-started/install.md` updated to recommend the unified form first; legacy two-command form preserved in a `<details>` block for users on shared dev machines.
+
+---
+
 ### 2026-05-29 — `bootstrap → "fill the templates" → refresh` is the wrong default
 
 **Symptom**: User runs `bootstrap Northwind`. Runner scaffolds folders + empty `boundaries.yml` + empty `integrations.yml`. SKILL.md tells the agent to reply *"now fill these two files and run refresh"*. User runs `refresh` immediately; refresh emits a configuration-blocked report and exits 0 with zero pulls. User's reaction: *"we know we need to fill them, why did the tool stop and ask? is this not a methodical do?"*

package/plugin/lib/Get-KushiConfig.ps1

@@ -180,12 +180,12 @@ Run ``npx kushi-agents@latest`` (vscode) or ``npx kushi-agents@latest --clawpilo
 
 if ($Path) { return $resolved }
 
-$raw = Get-Content -LiteralPath $resolved -Raw
+$rawText = Get-Content -LiteralPath $resolved -Raw
 
 if (-not $AllowPlaceholders) {
   $sentinelHit = $false
   foreach ($s in $script:Sentinels) {
-    if ($raw -like "*$s*") { $sentinelHit = $true; break }
+    if ($rawText -like "*$s*") { $sentinelHit = $true; break }
   }
   if ($sentinelHit) {
     throw @"
@@ -195,16 +195,16 @@ Edit the file with your actual values, or pass -AllowPlaceholders to bypass this
   }
 }
 
-if ($Raw) { return $raw }
+if ($Raw) { return $rawText }
 
 $parsed = switch ($ext) {
   'json' {
-    $raw | ConvertFrom-Json -Depth 100
+    $rawText | ConvertFrom-Json -Depth 100
   }
   { $_ -in 'yml','yaml' } {
     if (Get-Module -ListAvailable -Name 'powershell-yaml') {
       Import-Module powershell-yaml -ErrorAction Stop
-      ConvertFrom-Yaml -Yaml $raw
+      ConvertFrom-Yaml -Yaml $rawText
     } else {
       Write-Warning "powershell-yaml not installed; required-field validation skipped. Install with: Install-Module powershell-yaml -Scope CurrentUser"
       $null
@@ -223,5 +223,5 @@ Edit the file with your actual values, or pass -AllowPlaceholders to bypass this
   }
 }
 
-if ($null -eq $parsed) { return $raw }
+if ($null -eq $parsed) { return $rawText }
 return $parsed

package/src/get-kushi-config.test.mjs

@@ -0,0 +1,69 @@
+// Regression tests for plugin/lib/Get-KushiConfig.ps1.
+//
+// History: v5.7.1 had a SwitchParameter coercion bug. The script's
+// [switch] $Raw parameter collided with a local $raw = Get-Content variable
+// (PowerShell variables are case-insensitive). Assigning a string into the
+// typed switch parameter caused "Cannot convert String to SwitchParameter"
+// at the call site whenever the script was invoked from outside its own
+// scope.
+//
+// These tests install kushi into a temp dir, then invoke the live shipped
+// Get-KushiConfig.ps1 with various flag combinations and assert that the
+// invocation succeeds with no error stream output.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO = path.resolve(HERE, '..');
+
+function makeTmp(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+function freshInstall() {
+  const cwd = makeTmp('kushi-getconfig-');
+  const r = spawnSync(process.execPath, [path.join(REPO, 'bin', 'cli.mjs'), '--profile', 'full', '--skip-workiq-check', '--yes'], {
+    cwd, encoding: 'utf-8', shell: false,
+  });
+  assert.equal(r.status, 0, `installer failed: ${r.stderr || r.stdout}`);
+  return cwd;
+}
+
+function pwsh(cwd, args) {
+  return spawnSync('pwsh', ['-NoProfile', '-Command', ...args], {
+    cwd, encoding: 'utf-8', shell: false,
+  });
+}
+
+test('Get-KushiConfig.ps1 -Name m365-auth -Raw does not raise SwitchParameter coercion error', () => {
+  const cwd = freshInstall();
+  const script = path.join(cwd, '.kushi', 'lib', 'Get-KushiConfig.ps1');
+  const r = pwsh(cwd, [`& '${script}' -Name 'm365-auth' -Raw -AllowPlaceholders | Out-Null; if ($?) { 'OK' } else { 'FAIL' }`]);
+  assert.equal(r.status, 0, `pwsh exited ${r.status}; stderr=${r.stderr}`);
+  assert.match(r.stdout, /OK/, `expected OK, got stdout=${r.stdout} stderr=${r.stderr}`);
+  assert.doesNotMatch(r.stderr, /SwitchParameter/i, `SwitchParameter coercion error leaked: ${r.stderr}`);
+});
+
+test('Get-KushiConfig.ps1 -Name project-evidence -AllowPlaceholders -Raw works on fresh install', () => {
+  const cwd = freshInstall();
+  const script = path.join(cwd, '.kushi', 'lib', 'Get-KushiConfig.ps1');
+  const r = pwsh(cwd, [`& '${script}' -Name 'project-evidence' -AllowPlaceholders -Raw | Out-Null; if ($?) { 'OK' } else { 'FAIL' }`]);
+  assert.equal(r.status, 0, `pwsh exited ${r.status}; stderr=${r.stderr}`);
+  assert.match(r.stdout, /OK/, `expected OK, got stdout=${r.stdout} stderr=${r.stderr}`);
+  assert.doesNotMatch(r.stderr, /SwitchParameter/i, `SwitchParameter coercion error leaked: ${r.stderr}`);
+});
+
+test('Get-KushiConfig.ps1 -Path returns absolute resolved path', () => {
+  const cwd = freshInstall();
+  const script = path.join(cwd, '.kushi', 'lib', 'Get-KushiConfig.ps1');
+  const r = pwsh(cwd, [`& '${script}' -Name 'm365-auth' -Path`]);
+  assert.equal(r.status, 0, `pwsh exited ${r.status}; stderr=${r.stderr}`);
+  assert.match(r.stdout, /m365-auth\.json/, `expected resolved path, got stdout=${r.stdout}`);
+  assert.doesNotMatch(r.stderr, /SwitchParameter/i);
+});