kushi-agents 5.7.2 → 5.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "5.7.2",
+  "version": "5.7.3",
   "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 src/get-kushi-config.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 src/seed-config-derived.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,30 @@ Newest on top. Format defined in [`README.md`](./README.md). Use this file when
 
 ---
 
+### 2026-05-29 — `<auto>` placeholder check was blocking fresh installs
+
+**Symptom**: After a clean `npx kushi-agents@latest --all-hosts` install, the very first command users tried (`& '.\.kushi\lib\Get-KushiConfig.ps1' -Name 'm365-auth'`) threw a placeholder error citing `<auto>`. But `<auto>` is the explicit "Kushi will resolve this at runtime from identity / OS / WorkIQ" sentinel, by design — not an unfilled placeholder.
+
+**Root cause**: `<auto>` was wrongly listed alongside `__FILL_ME_IN__` in the blocking-sentinels array of `Get-KushiConfig.ps1`. That conflated two different concepts:
+
+- **Hard-blocking placeholders** (`__FILL_ME_IN__`, `<TENANT_ID>`, `<engagement-root>`, `<ProjectA>`): values that genuinely cannot be derived without user input. These should block.
+- **Runtime-resolution sentinels** (`<auto>`, `<YYYY-MM-DD>`): values that Kushi *can* derive at use-time from `os.userInfo()`, `Date.now()`, or WorkIQ whoami. These should NOT block; they're a feature flag for lazy fill.
+
+**Fix shipped (v5.7.3, 2026-05-29)**:
+
+1. **Removed `<auto>` from blocking sentinels** in `plugin/lib/Get-KushiConfig.ps1`. Added a comment explaining why so future contributors don't add it back.
+2. **Added `applyDerivedDefaults()` to `src/seed-config.mjs`** — runs at install time on freshly-seeded user/ files (never touches preserved/edited copies):
+   - `m365-auth.json#_meta.last_reviewed` ← today (YYYY-MM-DD)
+   - `m365-auth.json#_meta.owner` ← `${os.userInfo().username}@microsoft.com`
+   - `m365-auth.json#m365Auth.sharePointContext.localProjectsRoot` ← auto-detected from `$env:OneDriveCommercial`, `~/OneDrive - Microsoft/ISE/Engagement Assets`, or other `OneDrive - <Tenant>/ISE/Engagement Assets` paths if exactly one exists
+   - `project-evidence.yml#projects_root` ← same OneDrive auto-detection
+3. **Install now prints what was auto-filled** under `Config.user/  auto-filled defaults:` so users can see exactly what Kushi figured out and what they still need to edit.
+4. **Six new unit tests** in `src/seed-config-derived.test.mjs` + an integration test in `src/get-kushi-config.test.mjs` that does a real install and asserts `Get-KushiConfig.ps1 -Name m365-auth` passes (or fails ONLY with `__FILL_ME_IN__`, never `<auto>`).
+
+**Lesson**: When a config schema mixes hard-blocking placeholders with explicit "auto-resolve" sentinels, keep them in *separate lists*. Conflating them in one validation pass is a footgun: every new lazy-fill marker becomes a fresh-install bug. Also: install-time derivation is cheaper than runtime resolution — fill what you can mechanically (today's date, OS username, env vars, well-known paths) before a single user prompt is needed.
+
+---
+
 ### 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**:

package/plugin/lib/Get-KushiConfig.ps1

@@ -79,7 +79,10 @@ $script:RequiredFields = @{
 # Sentinel substrings that indicate "still a placeholder."
 $script:Sentinels = @(
   '__FILL_ME_IN__',
-  '<auto>',
+  # NOTE: '<auto>' is intentionally NOT in this list. It is a runtime-resolution
+  # marker meaning "Kushi will derive this from identity/env at use time" — not
+  # an unfilled placeholder. Callers that need a concrete value should resolve
+  # <auto> themselves (e.g. via WorkIQ whoami or os.userInfo()).
   '<TENANT_ID>',
   '<NOTEBOOK_ID>',
   '<NOTEBOOK_NAME>',
@@ -87,7 +90,9 @@ $script:Sentinels = @(
   '<SP_LOCAL_ROOT>',
   '<your-alias>',
   '<Your Full Name>',
-  'your.email@example.com'
+  'your.email@example.com',
+  '<engagement-root>',
+  '<ProjectA>'
 )
 
 function Test-Sentinel {

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

@@ -67,3 +67,26 @@ test('Get-KushiConfig.ps1 -Path returns absolute resolved path', () => {
   assert.match(r.stdout, /m365-auth\.json/, `expected resolved path, got stdout=${r.stdout}`);
   assert.doesNotMatch(r.stderr, /SwitchParameter/i);
 });
+
+test('Get-KushiConfig.ps1 -Name m365-auth (no -AllowPlaceholders) passes on fresh install with auto-filled defaults', () => {
+  // Regression for: bootstrap rejected fresh installs because the template's
+  // <auto>, <YYYY-MM-DD>, and __FILL_ME_IN__ markers all triggered the
+  // placeholder check. Fix: <auto> removed from blocking sentinels (it's a
+  // runtime-resolve marker), and seed-config now mechanically fills
+  // last_reviewed (today), _meta.owner (from $env:USER), and localProjectsRoot
+  // (auto-detected from OneDrive) at install time.
+  const cwd = freshInstall();
+  const script = path.join(cwd, '.kushi', 'lib', 'Get-KushiConfig.ps1');
+  const r = pwsh(cwd, [`& '${script}' -Name 'm365-auth' -Raw | Out-Null; if ($?) { 'OK' } else { 'FAIL' }`]);
+  // Note: localProjectsRoot may still be __FILL_ME_IN__ on machines with no OneDrive,
+  // so accept either (a) clean pass, or (b) a placeholder error that mentions ONLY
+  // __FILL_ME_IN__ (not <auto>, not <YYYY-MM-DD>).
+  if (r.stdout.includes('OK')) {
+    assert.doesNotMatch(r.stderr, /SwitchParameter/i);
+    return;
+  }
+  // If it failed, the only acceptable reason is genuine __FILL_ME_IN__ on machines
+  // without an auto-detectable OneDrive root.
+  assert.match(r.stderr, /__FILL_ME_IN__/, `expected only __FILL_ME_IN__ blocker, got: ${r.stderr}`);
+  assert.doesNotMatch(r.stderr, /<auto>/, `<auto> must NOT block — it is a runtime-resolve marker`);
+});

package/src/main.mjs

@@ -231,6 +231,10 @@ function printSeedReport(r, dispDestSlash) {
     for (const f of r.seededUser)    console.log(`      - ${f} -> seeded (edit before first bootstrap)`);
     for (const f of r.preservedUser) console.log(`      - ${f} -> preserved (already exists)`);
   }
+  if (r.derived && r.derived.length) {
+    console.log(`    auto-filled defaults:`);
+    for (const d of r.derived) console.log(`      - ${d.file}#${d.field} -> ${d.value}`);
+  }
   if (r.gitignore === 'created' || r.gitignore === 'appended') {
     console.log(`    .gitignore ${r.gitignore === 'created' ? 'created' : 'appended'} -> config/user/ excluded`);
   }

package/src/seed-config-derived.test.mjs

@@ -0,0 +1,117 @@
+// Tests for applyDerivedDefaults() in seed-config.mjs.
+//
+// Verifies that mechanically-derivable fields (today's date, OS-derived
+// identity, OneDrive auto-detection) are filled at install time so a fresh
+// install passes the Get-KushiConfig.ps1 placeholder check without manual
+// editing or `@Kushi setup` rituals.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { seedConfig } from './seed-config.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG = path.resolve(__dirname, '..');
+
+function tmp() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'kushi-derived-'));
+}
+
+test('applyDerivedDefaults: fills last_reviewed with today (m365-auth.json)', () => {
+  const dest = tmp();
+  try {
+    const r = seedConfig(PKG, dest);
+    assert.ok(r.seededUser.includes('m365-auth.json'));
+
+    const cfgPath = path.join(dest, 'config', 'user', 'm365-auth.json');
+    const obj = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+    const today = new Date().toISOString().slice(0, 10);
+    assert.equal(obj._meta.last_reviewed, today, 'last_reviewed should be today');
+    assert.notEqual(obj._meta.last_reviewed, '<YYYY-MM-DD>', 'placeholder should be replaced');
+
+    assert.ok(r.derived.some((d) => d.field === '_meta.last_reviewed'), 'derived list should record last_reviewed');
+  } finally {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+});
+
+test('applyDerivedDefaults: fills _meta.owner from OS username', () => {
+  const dest = tmp();
+  try {
+    seedConfig(PKG, dest);
+    const cfgPath = path.join(dest, 'config', 'user', 'm365-auth.json');
+    const obj = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+    const expectedUser = (os.userInfo().username || '').toLowerCase().replace(/[^a-z0-9._-]/g, '');
+    assert.equal(obj._meta.owner, `${expectedUser}@microsoft.com`);
+    assert.notEqual(obj._meta.owner, '<alias>@microsoft.com');
+  } finally {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+});
+
+test('applyDerivedDefaults: leaves <auto> identity markers alone (resolved at runtime)', () => {
+  const dest = tmp();
+  try {
+    seedConfig(PKG, dest);
+    const cfgPath = path.join(dest, 'config', 'user', 'm365-auth.json');
+    const obj = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+    // <auto> in defaultLinkOwner is a runtime-resolution sentinel; seed-config
+    // must NOT preempt it (callers like pull-onenote resolve via WorkIQ whoami).
+    assert.equal(obj.m365Auth.oneNote.defaultLinkOwner, '<auto>');
+  } finally {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+});
+
+test('applyDerivedDefaults: produces valid JSON (no syntax errors)', () => {
+  const dest = tmp();
+  try {
+    seedConfig(PKG, dest);
+    const cfgPath = path.join(dest, 'config', 'user', 'm365-auth.json');
+    const txt = fs.readFileSync(cfgPath, 'utf8');
+    assert.doesNotThrow(() => JSON.parse(txt), 'seeded m365-auth.json must be parseable');
+    assert.ok(txt.endsWith('\n'), 'should end with newline');
+  } finally {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+});
+
+test('applyDerivedDefaults: project-evidence.yml stays parseable as YAML', () => {
+  const dest = tmp();
+  try {
+    seedConfig(PKG, dest);
+    const cfgPath = path.join(dest, 'config', 'user', 'project-evidence.yml');
+    const txt = fs.readFileSync(cfgPath, 'utf8');
+    // Sanity: top-level keys still present
+    assert.match(txt, /^alias:/m);
+    assert.match(txt, /^email:/m);
+    assert.match(txt, /^projects_root:/m);
+  } finally {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+});
+
+test('applyDerivedDefaults: does not re-derive on reinstall when files preserved', () => {
+  const dest = tmp();
+  try {
+    seedConfig(PKG, dest);
+    const cfgPath = path.join(dest, 'config', 'user', 'm365-auth.json');
+    // Edit the seeded file as a user would
+    const obj = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+    obj._meta.last_reviewed = '2020-01-01';
+    fs.writeFileSync(cfgPath, JSON.stringify(obj, null, 2) + '\n');
+
+    // Reinstall — file is preserved, derived must not re-run on it
+    const r2 = seedConfig(PKG, dest);
+    assert.ok(r2.preservedUser.includes('m365-auth.json'));
+    assert.equal(r2.derived.length, 0, 'derived should be empty when no files were freshly seeded');
+
+    const after = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+    assert.equal(after._meta.last_reviewed, '2020-01-01', 'user-edited value preserved');
+  } finally {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+});

package/src/seed-config.mjs

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import {
   CONFIG_DIR,
@@ -86,12 +87,92 @@ export function seedConfig(sourcePkgDir, destAbsolute) {
   overwriteAlways(CONFIG_DOCTRINE_FILES, sharedDir, result.doctrine);
   overwriteAlways(CONFIG_EXAMPLE_FILES, sharedDir, result.examples);
 
+  // Post-process freshly-seeded user/ files: mechanically derive defaults
+  // (today's date, OneDrive root, OS-derived identity) so a brand-new install
+  // can be used immediately without manual editing or `@Kushi setup` rituals.
+  // Only runs on files we just seeded — never touches user-edited copies.
+  result.derived = applyDerivedDefaults(userDir, result.seededUser);
+
   // .gitignore at <dest>/.gitignore — append our marker block if not already present
   result.gitignore = ensureGitignore(destAbsolute, CONFIG_GITIGNORE_LINES);
 
   return result;
 }
 
+/**
+ * Mechanically derive defaults for freshly-seeded user-config files.
+ * Only modifies files in `seededFiles` (i.e. just-created in this run).
+ * Returns a list of {file, field, value} for the seed report.
+ */
+export function applyDerivedDefaults(userDir, seededFiles) {
+  const today = new Date().toISOString().slice(0, 10);
+  const username = (os.userInfo().username || '').toLowerCase().replace(/[^a-z0-9._-]/g, '');
+  const oneDriveRoot = detectOneDriveProjectsRoot();
+  const filled = [];
+
+  if (seededFiles.includes('m365-auth.json')) {
+    const f = path.join(userDir, 'm365-auth.json');
+    try {
+      const txt = fs.readFileSync(f, 'utf8');
+      const obj = JSON.parse(txt);
+      if (obj?._meta?.last_reviewed === '<YYYY-MM-DD>') {
+        obj._meta.last_reviewed = today; filled.push({ file: 'm365-auth.json', field: '_meta.last_reviewed', value: today });
+      }
+      if (username && obj?._meta?.owner === '<alias>@microsoft.com') {
+        obj._meta.owner = `${username}@microsoft.com`; filled.push({ file: 'm365-auth.json', field: '_meta.owner', value: obj._meta.owner });
+      }
+      if (oneDriveRoot && obj?.m365Auth?.sharePointContext?.localProjectsRoot === '__FILL_ME_IN__') {
+        obj.m365Auth.sharePointContext.localProjectsRoot = oneDriveRoot;
+        filled.push({ file: 'm365-auth.json', field: 'm365Auth.sharePointContext.localProjectsRoot', value: oneDriveRoot });
+      }
+      fs.writeFileSync(f, JSON.stringify(obj, null, 2) + '\n', 'utf8');
+    } catch { /* leave file as-is on parse error */ }
+  }
+
+  if (seededFiles.includes('project-evidence.yml')) {
+    const f = path.join(userDir, 'project-evidence.yml');
+    try {
+      let txt = fs.readFileSync(f, 'utf8');
+      if (oneDriveRoot && txt.includes("projects_root: '<engagement-root>'")) {
+        txt = txt.replace("projects_root: '<engagement-root>'", `projects_root: '${oneDriveRoot}'`);
+        filled.push({ file: 'project-evidence.yml', field: 'projects_root', value: oneDriveRoot });
+      }
+      fs.writeFileSync(f, txt, 'utf8');
+    } catch { /* leave file as-is on read error */ }
+  }
+
+  return filled;
+}
+
+/**
+ * Best-effort detection of the user's "Engagement Assets" parent folder.
+ * Probes (in order):
+ *   1. $env:OneDriveCommercial/ISE/Engagement Assets   (Windows env-var)
+ *   2. ~/OneDrive - Microsoft/ISE/Engagement Assets    (canonical Microsoft consultant path)
+ *   3. ~/OneDrive - <Tenant>/ISE/Engagement Assets     (single OneDrive-* folder match)
+ * Returns the first existing path or null.
+ */
+function detectOneDriveProjectsRoot() {
+  const candidates = [];
+  if (process.env.OneDriveCommercial) {
+    candidates.push(path.join(process.env.OneDriveCommercial, 'ISE', 'Engagement Assets'));
+  }
+  candidates.push(path.join(os.homedir(), 'OneDrive - Microsoft', 'ISE', 'Engagement Assets'));
+  // Probe other OneDrive - * tenants (e.g. for non-Microsoft consultants)
+  try {
+    const home = os.homedir();
+    for (const entry of fs.readdirSync(home, { withFileTypes: true })) {
+      if (entry.isDirectory() && entry.name.startsWith('OneDrive - ') && entry.name !== 'OneDrive - Microsoft') {
+        candidates.push(path.join(home, entry.name, 'ISE', 'Engagement Assets'));
+      }
+    }
+  } catch { /* homedir not readable - skip */ }
+  for (const p of candidates) {
+    try { if (fs.statSync(p).isDirectory()) return p; } catch { /* not present */ }
+  }
+  return null;
+}
+
 function ensureGitignore(destAbsolute, lines) {
   const target = path.join(destAbsolute, '.gitignore');
   const marker = lines[0];