kushi-agents 4.2.3 → 4.4.0

package/src/constants.mjs

@@ -20,21 +20,69 @@ export const CLAWPILOT_SKILL_DEST = 'SKILL.md';
 export const PLUGIN_SOURCE_DIR = 'plugin';
 
 /** Asset subdirectories under plugin/ that get copied. */
-export const ASSET_DIRS = ['agents', 'instructions', 'prompts', 'skills', 'templates', 'reference-packs'];
+export const ASSET_DIRS = ['agents', 'instructions', 'prompts', 'skills', 'templates', 'reference-packs', 'lib'];
 
 /**
  * User-editable config directory under the install destination.
- * Seeded on first install only; never overwritten on reinstall / --force / upgrade.
+ *
+ * v4.4.0 introduces a two-tier split inside config/:
+ *   - shared/  → team-owned, safe to commit. Doctrine + team defaults.
+ *   - user/    → per-contributor identity & local paths. Gitignored.
+ *
+ * Skills read configs via the Get-KushiConfig helper which checks
+ * user/ first, then shared/.
  */
 export const CONFIG_DIR = 'config';
+export const CONFIG_SHARED_SUBDIR = 'shared';
+export const CONFIG_USER_SUBDIR = 'user';
 
 /**
- * Files seeded into <dest>/config/ on first install only.
- * Each entry: { template: <path under plugin/templates/init/>, target: <name in config/> }
+ * Per-contributor config files (USER tier).
+ * Seeded only if absent; preserved on reinstall/upgrade.
+ * Written to <dest>/config/user/. Gitignored by installer.
  */
-export const CONFIG_SEED_FILES = [
+export const CONFIG_USER_SEED_FILES = [
   { template: 'init/project-evidence.template.yml', target: 'project-evidence.yml' },
-  { template: 'init/integrations.template.yml',     target: 'integrations.yml'     },
+  { template: 'init/m365-auth.template.json',       target: 'm365-auth.json'       },
+  { template: 'init/m365-mutable.template.json',    target: 'm365-mutable.json'    },
+];
+
+/**
+ * Team-shared config files (SHARED tier, seed-once).
+ * Seeded only if absent; preserved on reinstall.
+ * Written to <dest>/config/shared/. Safe to commit.
+ */
+export const CONFIG_SHARED_SEED_FILES = [
+  { template: 'init/integrations.template.yml', target: 'integrations.yml' },
+];
+
+/**
+ * Doctrine config files (SHARED tier, overwrite-always).
+ * Versioned by Kushi; overwritten on every install. User hand-edits are lost.
+ * Written to <dest>/config/shared/.
+ */
+export const CONFIG_DOCTRINE_FILES = [
+  { template: 'init/azuredevops.template.json',         target: 'azuredevops.json'         },
+  { template: 'init/dynamics365.template.json',         target: 'dynamics365.json'         },
+  { template: 'init/rsi-program-catalog.template.json', target: 'rsi-program-catalog.json' },
+];
+
+/**
+ * Example/reference scaffolds (SHARED tier, overwrite-always).
+ * Written to <dest>/config/shared/.
+ */
+export const CONFIG_EXAMPLE_FILES = [
+  { template: 'init/m365-auth.example.json',    target: 'm365-auth.json.example'    },
+  { template: 'init/m365-mutable.example.json', target: 'm365-mutable.json.example' },
+];
+
+/**
+ * Lines written to <dest>/.gitignore (created if missing, appended otherwise).
+ * Marks the per-user tier so contributors don't accidentally commit identity/paths.
+ */
+export const CONFIG_GITIGNORE_LINES = [
+  '# Kushi per-user config — never commit (created by kushi-agents installer)',
+  'config/user/',
 ];
 
 /** Files to exclude from consumer installs (relative to plugin/). */
@@ -43,18 +91,6 @@ export const EXCLUDED_FILES = [];
 /** Directories to exclude from consumer installs (relative to plugin/). */
 export const EXCLUDED_DIRS = [];
 
-/** Files copied to the TARGET project's .github/ directory. */
-export const PROJECT_GITHUB_FILES = [];
-
-/** Directories copied to the TARGET project's .github/ directory. */
-export const PROJECT_GITHUB_DIRS = ['config'];
-
-/** Project-level .github files that must never be copied into consumer projects. */
-export const PROJECT_GITHUB_EXCLUDED_FILES = [
-  'config/m365-auth.json',
-  'config/m365-mutable.json'
-];
-
 /**
  * Files / directories that indicate the cwd is a sane install target.
  *

package/src/copy-assets.mjs

@@ -5,9 +5,6 @@ import {
   EXCLUDED_FILES,
   EXCLUDED_DIRS,
   PLUGIN_SOURCE_DIR,
-  PROJECT_GITHUB_FILES,
-  PROJECT_GITHUB_DIRS,
-  PROJECT_GITHUB_EXCLUDED_FILES,
 } from './constants.mjs';
 
 /**
@@ -97,31 +94,6 @@ function copyDirFiltered(src, dest, assetDir, relPrefix = '', includeFilter) {
  * @param {string} projectDir
  * @param {string} [relPrefix='']
  */
-function copyProjectDirFiltered(src, dest, projectDir, relPrefix = '') {
-  fs.mkdirSync(dest, { recursive: true });
-
-  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-    const relPath = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
-    const excludeKey = `${projectDir}/${relPath}`;
-
-    if (entry.isDirectory()) {
-      copyProjectDirFiltered(srcPath, destPath, projectDir, relPrefix ? `${relPrefix}/${entry.name}` : entry.name);
-      continue;
-    }
-
-    if (PROJECT_GITHUB_EXCLUDED_FILES.includes(excludeKey)) continue;
-
-    fs.cpSync(srcPath, destPath, { force: true });
-  }
-}
-
-/**
- * Count files recursively in a directory.
- * @param {string} dir
- * @returns {number}
- */
 function countFiles(dir) {
   let count = 0;
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
@@ -133,51 +105,3 @@ function countFiles(dir) {
   }
   return count;
 }
-
-/**
- * Copy project-level files (hooks, copilot-instructions) to the target
- * project's .github/ directory. Does not overwrite existing files.
- *
- * @param {string} sourcePkgDir – root of the npm package
- * @returns {{ copied: string[], skipped: string[] }}
- */
-export function copyProjectFiles(sourcePkgDir) {
-  const projectGitHub = path.join(process.cwd(), '.github');
-  const srcGitHub = path.join(sourcePkgDir, '.github');
-
-  const copied = [];
-  const skipped = [];
-
-  for (const file of PROJECT_GITHUB_FILES) {
-    const src = path.join(srcGitHub, file);
-    const dest = path.join(projectGitHub, file);
-
-    if (!fs.existsSync(src)) continue;
-
-    if (fs.existsSync(dest)) {
-      skipped.push(`.github/${file}`);
-      continue;
-    }
-
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    fs.cpSync(src, dest);
-    copied.push(`.github/${file}`);
-  }
-
-  for (const dir of PROJECT_GITHUB_DIRS) {
-    const src = path.join(srcGitHub, dir);
-    const dest = path.join(projectGitHub, dir);
-
-    if (!fs.existsSync(src)) continue;
-
-    if (fs.existsSync(dest)) {
-      skipped.push(`.github/${dir}/`);
-      continue;
-    }
-
-    copyProjectDirFiltered(src, dest, dir);
-    copied.push(`.github/${dir}/`);
-  }
-
-  return { copied, skipped };
-}

package/src/main.mjs

@@ -13,7 +13,7 @@ import {
   PROJECT_MARKERS,
 } from './constants.mjs';
 import { promptForDestination } from './prompt.mjs';
-import { copyAssets, copyProjectFiles } from './copy-assets.mjs';
+import { copyAssets } from './copy-assets.mjs';
 import { mergeSettings } from './settings.mjs';
 import { mergeCopilotInstructions } from './copilot-instructions.mjs';
 import { seedConfig } from './seed-config.mjs';
@@ -134,12 +134,8 @@ async function installVscode(options, resolved, version) {
   const manifestPath = writeInstalledManifest(fullDest, resolved, version);
   console.log(`    - kushi-install.json (profile manifest)`);
 
-  const { seeded, preserved } = seedConfig(PKG_ROOT, fullDest);
-  if (seeded.length > 0 || preserved.length > 0) {
-    console.log(`\n  Config (.kushi/config/ — user-editable, preserved across upgrades):`);
-    for (const f of seeded)    console.log(`    - ${f} -> seeded from template`);
-    for (const f of preserved) console.log(`    - ${f} -> preserved (already exists)`);
-  }
+  const seedRes = seedConfig(PKG_ROOT, fullDest);
+  printSeedReport(seedRes, `${dest}/`);
 
   if (!options.noSettings) {
     const { created, keysAdded, keysUnchanged } = mergeSettings(
@@ -176,19 +172,6 @@ async function installVscode(options, resolved, version) {
     console.log('\n  Skipped .github/copilot-instructions.md (--no-instructions)');
   }
 
-  const { copied: projCopied, skipped: projSkipped } = copyProjectFiles(PKG_ROOT);
-  if (projCopied.length > 0) {
-    console.log('\n  Copied project files to .github/');
-    for (const f of projCopied) {
-      console.log(`    - ${f}`);
-    }
-  }
-  if (projSkipped.length > 0) {
-    for (const f of projSkipped) {
-      console.log(`    - ${f} -> unchanged (already exists)`);
-    }
-  }
-
   printPostInstall(resolved, '@Kushi');
 }
 
@@ -233,12 +216,8 @@ async function installClawpilot(options, resolved, version) {
   writeInstalledManifest(fullDest, resolved, version);
   console.log(`    - kushi-install.json (profile manifest)`);
 
-  const { seeded, preserved } = seedConfig(PKG_ROOT, fullDest);
-  if (seeded.length > 0 || preserved.length > 0) {
-    console.log(`\n  Config (${displayDest}\\config\\ — user-editable, preserved across upgrades):`);
-    for (const f of seeded)    console.log(`    - ${f} -> seeded from template`);
-    for (const f of preserved) console.log(`    - ${f} -> preserved (already exists)`);
-  }
+  const seedRes = seedConfig(PKG_ROOT, fullDest);
+  printSeedReport(seedRes, `${displayDest}\\`);
 
   // Mirror agents/kushi.agent.md as top-level SKILL.md for Clawpilot discovery.
   const agentSrc = path.join(PKG_ROOT, PLUGIN_SOURCE_DIR, CLAWPILOT_AGENT_SOURCE);
@@ -253,6 +232,31 @@ async function installClawpilot(options, resolved, version) {
   printPostInstall(resolved, 'kushi');
 }
 
+function printSeedReport(r, dispDestSlash) {
+  const total =
+    r.seededUser.length + r.seededShared.length +
+    r.preservedUser.length + r.preservedShared.length +
+    r.doctrine.length + r.examples.length;
+  if (total === 0 && r.gitignore === 'unchanged') return;
+
+  console.log(`\n  Config (${dispDestSlash}config/):`);
+  if (r.seededShared.length || r.preservedShared.length || r.doctrine.length || r.examples.length) {
+    console.log(`    shared/  (team-owned, safe to commit)`);
+    for (const f of r.seededShared)    console.log(`      - ${f} -> seeded (team default; preserved on reinstall)`);
+    for (const f of r.preservedShared) console.log(`      - ${f} -> preserved (already exists)`);
+    for (const f of r.doctrine)        console.log(`      - ${f} -> updated (Kushi-versioned doctrine; do not hand-edit)`);
+    for (const f of r.examples)        console.log(`      - ${f} -> refreshed (reference scaffold)`);
+  }
+  if (r.seededUser.length || r.preservedUser.length) {
+    console.log(`    user/    (per-contributor; gitignored)`);
+    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.gitignore === 'created' || r.gitignore === 'appended') {
+    console.log(`    .gitignore ${r.gitignore === 'created' ? 'created' : 'appended'} -> config/user/ excluded`);
+  }
+}
+
 function printPostInstall(resolved, prefix) {
   console.log(`\n  Done. Profile "${resolved.profile}" installed. Available verbs:`);
   for (const verb of resolved.verbs) {

package/src/seed-config.mjs

@@ -2,43 +2,108 @@ import fs from 'node:fs';
 import path from 'node:path';
 import {
   CONFIG_DIR,
-  CONFIG_SEED_FILES,
+  CONFIG_SHARED_SUBDIR,
+  CONFIG_USER_SUBDIR,
+  CONFIG_USER_SEED_FILES,
+  CONFIG_SHARED_SEED_FILES,
+  CONFIG_DOCTRINE_FILES,
+  CONFIG_EXAMPLE_FILES,
+  CONFIG_GITIGNORE_LINES,
   PLUGIN_SOURCE_DIR,
 } from './constants.mjs';
 
 /**
- * Seed <dest>/config/ with user-editable config files on FIRST INSTALL ONLY.
+ * Seed <dest>/config/ with config files using a two-tier shared/ + user/ layout.
  *
- * Rules:
- *   - If <dest>/config/<file> already exists → skip (never overwrite).
- *   - Behavior is identical regardless of --force; config/ is user territory.
- *   - Returns a per-file result so the installer can summarize what happened.
+ *   <dest>/config/
+ *     shared/   ← team-owned, safe to commit (doctrine + team defaults + .example scaffolds)
+ *     user/     ← per-contributor identity & local paths (gitignored)
+ *
+ * Policies:
+ *   - USER SEED (user/, seed-once): copied only if absent. Preserved on reinstall.
+ *   - SHARED SEED (shared/, seed-once): copied only if absent. Preserved on reinstall.
+ *   - DOCTRINE (shared/, overwrite-always): always rewritten — Kushi-versioned.
+ *   - EXAMPLES (shared/, overwrite-always): always rewritten — reference scaffolds.
+ *
+ * Also writes <dest>/.gitignore with `config/user/` to prevent accidental commits.
  *
  * @param {string} sourcePkgDir – root of the npm package
  * @param {string} destAbsolute – absolute install destination (e.g. <workspace>/.kushi)
- * @returns {{ seeded: string[], preserved: string[] }}
+ * @returns {{
+ *   seededUser: string[],     // user/ files freshly created
+ *   seededShared: string[],   // shared/ seed-once files freshly created
+ *   preservedUser: string[],  // user/ files left untouched (already existed)
+ *   preservedShared: string[],// shared/ seed-once files left untouched
+ *   doctrine: string[],       // shared/ doctrine files written (always)
+ *   examples: string[],       // shared/ .example files written (always)
+ *   gitignore: 'created' | 'appended' | 'unchanged' | 'skipped',
+ * }}
  */
 export function seedConfig(sourcePkgDir, destAbsolute) {
-  const configDir = path.join(destAbsolute, CONFIG_DIR);
-  fs.mkdirSync(configDir, { recursive: true });
-
-  const seeded = [];
-  const preserved = [];
+  const sharedDir = path.join(destAbsolute, CONFIG_DIR, CONFIG_SHARED_SUBDIR);
+  const userDir = path.join(destAbsolute, CONFIG_DIR, CONFIG_USER_SUBDIR);
+  fs.mkdirSync(sharedDir, { recursive: true });
+  fs.mkdirSync(userDir, { recursive: true });
 
-  for (const { template, target } of CONFIG_SEED_FILES) {
-    const src = path.join(sourcePkgDir, PLUGIN_SOURCE_DIR, 'templates', template);
-    const dst = path.join(configDir, target);
+  const result = {
+    seededUser: [],
+    seededShared: [],
+    preservedUser: [],
+    preservedShared: [],
+    doctrine: [],
+    examples: [],
+    gitignore: 'unchanged',
+  };
 
-    if (!fs.existsSync(src)) continue;
+  const seedOnce = (specs, destDir, seededList, preservedList) => {
+    for (const { template, target } of specs) {
+      const src = path.join(sourcePkgDir, PLUGIN_SOURCE_DIR, 'templates', template);
+      const dst = path.join(destDir, target);
+      if (!fs.existsSync(src)) continue;
+      if (fs.existsSync(dst)) {
+        preservedList.push(target);
+        continue;
+      }
+      fs.cpSync(src, dst);
+      seededList.push(target);
+    }
+  };
 
-    if (fs.existsSync(dst)) {
-      preserved.push(target);
-      continue;
+  const overwriteAlways = (specs, destDir, list) => {
+    for (const { template, target } of specs) {
+      const src = path.join(sourcePkgDir, PLUGIN_SOURCE_DIR, 'templates', template);
+      const dst = path.join(destDir, target);
+      if (!fs.existsSync(src)) continue;
+      fs.cpSync(src, dst, { force: true });
+      list.push(target);
     }
+  };
 
-    fs.cpSync(src, dst);
-    seeded.push(target);
-  }
+  // user/ tier
+  seedOnce(CONFIG_USER_SEED_FILES, userDir, result.seededUser, result.preservedUser);
+  // shared/ tier
+  seedOnce(CONFIG_SHARED_SEED_FILES, sharedDir, result.seededShared, result.preservedShared);
+  overwriteAlways(CONFIG_DOCTRINE_FILES, sharedDir, result.doctrine);
+  overwriteAlways(CONFIG_EXAMPLE_FILES, sharedDir, result.examples);
 
-  return { seeded, preserved };
+  // .gitignore at <dest>/.gitignore — append our marker block if not already present
+  result.gitignore = ensureGitignore(destAbsolute, CONFIG_GITIGNORE_LINES);
+
+  return result;
+}
+
+function ensureGitignore(destAbsolute, lines) {
+  const target = path.join(destAbsolute, '.gitignore');
+  const marker = lines[0];
+  const block = lines.join('\n') + '\n';
+
+  if (!fs.existsSync(target)) {
+    fs.writeFileSync(target, block, 'utf8');
+    return 'created';
+  }
+  const existing = fs.readFileSync(target, 'utf8');
+  if (existing.includes(marker)) return 'unchanged';
+  const sep = existing.endsWith('\n') ? '\n' : '\n\n';
+  fs.writeFileSync(target, existing + sep + block, 'utf8');
+  return 'appended';
 }

package/src/seed-config.test.mjs

@@ -0,0 +1,150 @@
+// Tests for seed-config.mjs — verifies the two-tier shared/ + user/ seeding.
+
+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';
+import {
+  CONFIG_DOCTRINE_FILES,
+  CONFIG_EXAMPLE_FILES,
+  CONFIG_USER_SEED_FILES,
+  CONFIG_SHARED_SEED_FILES,
+} from './constants.mjs';
+import { loadKushiConfig, resolveKushiConfigPath } from './config-loader.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG = path.resolve(__dirname, '..');
+
+function tmp() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'kushi-seed-'));
+}
+
+test('seedConfig: fresh install populates shared/ and user/ correctly', () => {
+  const dest = tmp();
+  try {
+    const r = seedConfig(PKG, dest);
+
+    const userTargets    = CONFIG_USER_SEED_FILES.map((f) => f.target);
+    const sharedTargets  = CONFIG_SHARED_SEED_FILES.map((f) => f.target);
+    const doctrineTargets = CONFIG_DOCTRINE_FILES.map((f) => f.target);
+    const exampleTargets = CONFIG_EXAMPLE_FILES.map((f) => f.target);
+
+    for (const t of userTargets)    assert.ok(r.seededUser.includes(t),   `seededUser includes ${t}`);
+    for (const t of sharedTargets)  assert.ok(r.seededShared.includes(t), `seededShared includes ${t}`);
+    for (const t of doctrineTargets) assert.ok(r.doctrine.includes(t),    `doctrine includes ${t}`);
+    for (const t of exampleTargets) assert.ok(r.examples.includes(t),     `examples includes ${t}`);
+
+    for (const t of userTargets) {
+      assert.ok(fs.existsSync(path.join(dest, 'config', 'user', t)), `user/${t} on disk`);
+    }
+    for (const t of [...sharedTargets, ...doctrineTargets, ...exampleTargets]) {
+      assert.ok(fs.existsSync(path.join(dest, 'config', 'shared', t)), `shared/${t} on disk`);
+    }
+
+    assert.equal(r.gitignore, 'created');
+    const gi = fs.readFileSync(path.join(dest, '.gitignore'), 'utf8');
+    assert.ok(gi.includes('config/user/'), '.gitignore contains config/user/');
+  } finally {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+});
+
+test('seedConfig: re-run preserves user/ and shared/ seed-once files', () => {
+  const dest = tmp();
+  try {
+    seedConfig(PKG, dest);
+    const userFile = path.join(dest, 'config', 'user', 'project-evidence.yml');
+    const sharedSeed = path.join(dest, 'config', 'shared', 'integrations.yml');
+    fs.writeFileSync(userFile, 'alias: edited-by-user\n');
+    fs.writeFileSync(sharedSeed, '# team-edited\n');
+
+    const r2 = seedConfig(PKG, dest);
+
+    assert.ok(r2.preservedUser.includes('project-evidence.yml'));
+    assert.ok(r2.preservedShared.includes('integrations.yml'));
+    assert.equal(fs.readFileSync(userFile, 'utf8'), 'alias: edited-by-user\n');
+    assert.equal(fs.readFileSync(sharedSeed, 'utf8'), '# team-edited\n');
+    assert.equal(r2.gitignore, 'unchanged');
+  } finally {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+});
+
+test('seedConfig: doctrine and examples are overwritten on every install', () => {
+  const dest = tmp();
+  try {
+    seedConfig(PKG, dest);
+    const doc = path.join(dest, 'config', 'shared', 'azuredevops.json');
+    const ex  = path.join(dest, 'config', 'shared', 'm365-auth.json.example');
+    fs.writeFileSync(doc, '{"tampered":true}');
+    fs.writeFileSync(ex, '{}');
+
+    const r2 = seedConfig(PKG, dest);
+
+    assert.ok(r2.doctrine.includes('azuredevops.json'));
+    assert.ok(r2.examples.includes('m365-auth.json.example'));
+    const docRe = fs.readFileSync(doc, 'utf8');
+    const exRe  = fs.readFileSync(ex, 'utf8');
+    assert.ok(!docRe.includes('tampered'), 'doctrine restored');
+    assert.ok(exRe.length > 10, 'example restored');
+  } finally {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+});
+
+test('seedConfig: .gitignore is appended when file exists without marker', () => {
+  const dest = tmp();
+  try {
+    fs.writeFileSync(path.join(dest, '.gitignore'), '# pre-existing\nnode_modules/\n');
+    const r = seedConfig(PKG, dest);
+    assert.equal(r.gitignore, 'appended');
+    const gi = fs.readFileSync(path.join(dest, '.gitignore'), 'utf8');
+    assert.ok(gi.includes('node_modules/'), 'preserved existing content');
+    assert.ok(gi.includes('config/user/'), 'appended Kushi marker');
+  } finally {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+});
+
+test('config-loader: resolves user/ before shared/', () => {
+  const workspace = tmp();
+  const dest = path.join(workspace, '.kushi');
+  try {
+    seedConfig(PKG, dest);
+    const sharedResolved = resolveKushiConfigPath('azuredevops', { workspace });
+    assert.ok(sharedResolved.includes(path.join('config', 'shared', 'azuredevops.json')));
+
+    const userShadow = path.join(dest, 'config', 'user', 'azuredevops.json');
+    fs.writeFileSync(userShadow, '{"override":true}');
+    const userResolved = resolveKushiConfigPath('azuredevops', { workspace });
+    assert.equal(userResolved, userShadow);
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
+test('config-loader: throws on placeholder by default; -allowPlaceholders bypasses', () => {
+  const workspace = tmp();
+  const dest = path.join(workspace, '.kushi');
+  try {
+    seedConfig(PKG, dest);
+    assert.throws(() => loadKushiConfig('project-evidence', { workspace, raw: true }),
+      /placeholder/i);
+    const txt = loadKushiConfig('project-evidence', { workspace, raw: true, allowPlaceholders: true });
+    assert.equal(typeof txt, 'string');
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
+test('config-loader: throws with actionable message when missing', () => {
+  const dest = tmp();
+  try {
+    assert.throws(() => loadKushiConfig('nonexistent-config', { workspace: dest }), /not found/i);
+  } finally {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+});