kenaz 0.0.0-stage → 0.3.2

package/core/.specialist/tests/runtime-discovery/resolver-priority.test.js

@@ -0,0 +1,693 @@
+#!/usr/bin/env node
+/**
+ * resolver-priority.test.js
+ *
+ * Contract assertions: each canonical resolver respects its documented priority
+ * chain. A test failure means a resolver short-circuited or reordered levels.
+ *
+ * Resolvers under test:
+ *   1. resolveCoreDir        .claude/hooks/core-resolve.js
+ *   2. resolveTasksDir       .collaboration/core/task-api.js
+ *   3. resolveKenazPath      .specialist/tools/phase-gate.js (via inline probe)
+ *   4. install.js wrapper    .collaboration/hooks/install.js  (via subprocess, Unix only)
+ *   5. Rust resolve_core_path dashboard/src-tauri/src/features/task/manager.rs
+ *                            (JS mirror — see resolver-symmetry.test.js for diff report)
+ *
+ * Priority chain for resolveCoreDir / install.js bash wrapper:
+ *   L1  .kenaz/project.yaml → core_path  (validated: existsSync + isDirectory)
+ *   L2  KENAZ_SOURCE_DIR env var          (validated: isDirectory)
+ *   L3  Auto-discovery                    (LOCALAPPDATA / ~/.local / walk-up __dirname)
+ *   L4  ~/.kenaz/projects.json → is_core  (validated: isDirectory)
+ *
+ * NOTE: Rust resolver has a DIFFERENT chain (KENAZ_SOURCE_DIR is step 0, before
+ * project.yaml). The symmetry test in resolver-symmetry.test.js documents and
+ * detects divergences between the two implementations.
+ *
+ * Exit codes: 0 = all pass, 1 = one or more failures.
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const os   = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function uid() { return crypto.randomBytes(4).toString('hex'); }
+
+function mkTemp(prefix) {
+  const dir = path.join(os.tmpdir(), `kenaz-prio-${prefix}-${uid()}`);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function ensureDir(p) { fs.mkdirSync(p, { recursive: true }); }
+
+function writeFile(p, content) {
+  ensureDir(path.dirname(p));
+  fs.writeFileSync(p, content, 'utf8');
+}
+
+function fwdSlash(p) { return p.replace(/\\/g, '/'); }
+
+function normPath(p) {
+  if (!p) return null;
+  try { p = fs.realpathSync(p); } catch { /* best-effort */ }
+  return p.replace(/\\/g, '/').replace(/\/$/, '');
+}
+
+/**
+ * Temporarily override process.env for the duration of fn(), then restore.
+ * Pass undefined as value to delete the key during fn().
+ */
+function withEnv(overrides, fn) {
+  const saved = {};
+  for (const k of Object.keys(overrides)) {
+    saved[k] = Object.prototype.hasOwnProperty.call(process.env, k)
+      ? process.env[k] : undefined;
+    if (overrides[k] === undefined) delete process.env[k];
+    else process.env[k] = overrides[k];
+  }
+  try {
+    return fn();
+  } finally {
+    for (const [k, v] of Object.entries(saved)) {
+      if (v === undefined) delete process.env[k];
+      else process.env[k] = v;
+    }
+  }
+}
+
+// ── test runner ───────────────────────────────────────────────────────────────
+
+const RESULTS = [];
+let _suite = '';
+
+function suite(name) {
+  _suite = name;
+  process.stdout.write(`\n[${name}]\n`);
+}
+
+function test(name, fn) {
+  const t0 = Date.now();
+  try {
+    fn();
+    const ms = Date.now() - t0;
+    RESULTS.push({ suite: _suite, name, status: 'pass', ms });
+    process.stdout.write(`  ✓ ${name} (${ms}ms)\n`);
+  } catch (err) {
+    const ms = Date.now() - t0;
+    RESULTS.push({ suite: _suite, name, status: 'fail', ms, error: err.message });
+    process.stderr.write(`  ✗ ${name}\n    ${err.message}\n`);
+  }
+}
+
+function assert(cond, msg) {
+  if (!cond) throw new Error(msg || 'assertion failed');
+}
+
+function assertEqual(actual, expected, label) {
+  const a = normPath(actual);
+  const e = normPath(expected);
+  if (a !== e) {
+    throw new Error(
+      `${label}\n    actual:   ${a ?? '(null)'}\n    expected: ${e ?? '(null)'}`
+    );
+  }
+}
+
+// ── project root resolution ───────────────────────────────────────────────────
+
+function findProjectRoot() {
+  let dir = __dirname;
+  for (let i = 0; i < 12; i++) {
+    if (fs.existsSync(path.join(dir, '.specialist'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.cwd();
+}
+
+const PROJECT_ROOT    = findProjectRoot();
+const CORE_RESOLVE_JS = path.join(PROJECT_ROOT, '.claude', 'hooks', 'core-resolve.js');
+const TASK_API_JS     = path.join(PROJECT_ROOT, '.collaboration', 'core', 'task-api.js');
+
+// Import JS resolvers
+const { resolveCoreDir } = require(CORE_RESOLVE_JS);
+const { resolveTasksDir } = require(TASK_API_JS);
+
+// ══════════════════════════════════════════════════════════════════════════════
+//  SUITE 1 — resolveCoreDir priority chain  (core-resolve.js)
+// ══════════════════════════════════════════════════════════════════════════════
+
+suite('resolveCoreDir [.claude/hooks/core-resolve.js] priority chain');
+
+// L1 beats L2: project.yaml valid core_path wins even when KENAZ_SOURCE_DIR set
+test('[resolver=resolveCoreDir][level=L1>L2] project.yaml valid core_path wins over KENAZ_SOURCE_DIR', () => {
+  const projectDir = mkTemp('rc-l1-beats-l2');
+  const coreDir    = mkTemp('rc-l1-core');
+  const envDir     = mkTemp('rc-l2-env');
+  try {
+    writeFile(
+      path.join(projectDir, '.kenaz', 'project.yaml'),
+      `name: test\ncore_path: "${fwdSlash(coreDir)}"\n`
+    );
+    const result = withEnv({ KENAZ_SOURCE_DIR: envDir }, () => resolveCoreDir(projectDir));
+    assertEqual(result, coreDir,
+      '[resolver=resolveCoreDir][fixture=project-yaml-valid][level=L1>L2] ' +
+      'project.yaml core_path should win over KENAZ_SOURCE_DIR');
+  } finally {
+    fs.rmSync(projectDir, { recursive: true, force: true });
+    fs.rmSync(coreDir,    { recursive: true, force: true });
+    fs.rmSync(envDir,     { recursive: true, force: true });
+  }
+});
+
+// L1 skipped (sentinel) → L2 wins
+test('[resolver=resolveCoreDir][level=L1→L2] sentinel in project.yaml → KENAZ_SOURCE_DIR wins', () => {
+  const projectDir = mkTemp('rc-l1-sentinel');
+  const envDir     = mkTemp('rc-l2-env');
+  try {
+    writeFile(
+      path.join(projectDir, '.kenaz', 'project.yaml'),
+      `name: test\ncore_path: __kenaz_core__\n`
+    );
+    const result = withEnv({ KENAZ_SOURCE_DIR: envDir }, () => resolveCoreDir(projectDir));
+    assertEqual(result, envDir,
+      '[resolver=resolveCoreDir][fixture=sentinel][level=L1→L2] ' +
+      '__kenaz_core__ sentinel must be skipped; KENAZ_SOURCE_DIR should win');
+  } finally {
+    fs.rmSync(projectDir, { recursive: true, force: true });
+    fs.rmSync(envDir,     { recursive: true, force: true });
+  }
+});
+
+// L1 skipped (stale path) → L2 wins
+test('[resolver=resolveCoreDir][level=L1→L2] stale core_path in project.yaml → KENAZ_SOURCE_DIR wins', () => {
+  const projectDir = mkTemp('rc-l1-stale');
+  const stalePath  = path.join(os.tmpdir(), `kenaz-nonexist-${uid()}`);
+  const envDir     = mkTemp('rc-l2-env');
+  try {
+    assert(!fs.existsSync(stalePath), 'precondition: stale path must not exist');
+    writeFile(
+      path.join(projectDir, '.kenaz', 'project.yaml'),
+      `name: test\ncore_path: "${fwdSlash(stalePath)}"\n`
+    );
+    const result = withEnv({ KENAZ_SOURCE_DIR: envDir }, () => resolveCoreDir(projectDir));
+    assertEqual(result, envDir,
+      '[resolver=resolveCoreDir][fixture=stale-core-path][level=L1→L2] ' +
+      'stale core_path (non-existent dir) must be skipped; KENAZ_SOURCE_DIR should win');
+  } finally {
+    fs.rmSync(projectDir, { recursive: true, force: true });
+    fs.rmSync(envDir,     { recursive: true, force: true });
+  }
+});
+
+// L2 beats L3+L4: no valid project.yaml, KENAZ_SOURCE_DIR valid → wins before auto-discover
+test('[resolver=resolveCoreDir][level=L2>L3+L4] KENAZ_SOURCE_DIR wins when no project.yaml', () => {
+  const projectDir = mkTemp('rc-l2-no-yaml');
+  const envDir     = mkTemp('rc-l2-env');
+  try {
+    // No .kenaz/project.yaml in projectDir
+    const result = withEnv({ KENAZ_SOURCE_DIR: envDir }, () => resolveCoreDir(projectDir));
+    assertEqual(result, envDir,
+      '[resolver=resolveCoreDir][fixture=no-project-yaml][level=L2>L3+L4] ' +
+      'KENAZ_SOURCE_DIR should win when project.yaml absent (auto-discover should not run)');
+  } finally {
+    fs.rmSync(projectDir, { recursive: true, force: true });
+    fs.rmSync(envDir,     { recursive: true, force: true });
+  }
+});
+
+// L2 invalid → L3 auto-discover runs and returns a valid directory
+test('[resolver=resolveCoreDir][level=L2→L3] invalid KENAZ_SOURCE_DIR → auto-discover runs', () => {
+  const projectDir    = mkTemp('rc-l3-auto');
+  const nonExistEnv   = path.join(os.tmpdir(), `kenaz-no-env-${uid()}`);
+  try {
+    // No project.yaml; KENAZ_SOURCE_DIR points to non-existent path
+    const result = withEnv({ KENAZ_SOURCE_DIR: nonExistEnv }, () => resolveCoreDir(projectDir));
+    // Auto-discover via __dirname walk-up will find the KenazAI project root
+    // (since core-resolve.js lives inside it). Assert we get something valid.
+    if (result !== null) {
+      assert(
+        fs.existsSync(result) && fs.statSync(result).isDirectory(),
+        `[resolver=resolveCoreDir][level=L3] auto-discover returned "${result}" which is not a valid directory`
+      );
+    }
+    process.stdout.write(`    auto-discover resolved: ${result}\n`);
+  } finally {
+    fs.rmSync(projectDir, { recursive: true, force: true });
+  }
+});
+
+// L4: projects.json is_core is last-resort fallback.
+// Uses a subprocess with an inline probe so __dirname walk-up doesn't find project root.
+test('[resolver=resolveCoreDir][level=L4] projects.json is_core is last-resort fallback', () => {
+  const fakeHome    = mkTemp('rc-l4-home');
+  const coreProject = mkTemp('rc-l4-core');
+  const outsideDir  = mkTemp('rc-l4-outside');
+  try {
+    // Set up fake ~/.kenaz/projects.json with is_core=true
+    writeFile(
+      path.join(fakeHome, '.kenaz', 'projects.json'),
+      JSON.stringify({
+        currentProjectId: 'proj-active-001',
+        projects: [
+          {
+            id: 'proj-core-000',
+            name: 'KenazAI Core',
+            path: fwdSlash(coreProject),
+            is_core: true,
+          },
+          {
+            id: 'proj-active-001',
+            name: 'Active Project',
+            path: fwdSlash(outsideDir),
+            is_core: false,
+          },
+        ],
+      }, null, 2)
+    );
+
+    // Inline probe: implements full priority chain with __dirname = outsideDir,
+    // so walk-up auto-discover cannot find the KenazAI project root.
+    const probeCode = `
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+function isDir(p) {
+  try { return Boolean(p) && fs.existsSync(p) && fs.statSync(p).isDirectory(); } catch { return false; }
+}
+function autoDiscover() {
+  const cands = [];
+  if (process.env.LOCALAPPDATA) {
+    cands.push(path.join(process.env.LOCALAPPDATA, 'Kenaz Dashboard', 'kenaz-core'));
+  }
+  const h = process.env.HOME || process.env.USERPROFILE || os.homedir();
+  if (h) cands.push(path.join(h, '.local', 'share', 'kenaz-dashboard', 'kenaz-core'));
+  // Walk up from __dirname (probe lives in outsideDir — not inside KenazAI project)
+  let dir = __dirname;
+  for (let i = 0; i < 8; i++) {
+    if (isDir(path.join(dir, '.specialist'))) { cands.unshift(dir); break; }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return cands.find(isDir) || null;
+}
+const projectPath = process.env.PROBE_PROJECT_PATH;
+// L1: project.yaml
+try {
+  const yaml = fs.readFileSync(path.join(projectPath, '.kenaz', 'project.yaml'), 'utf8');
+  const m = yaml.match(/core_path:\\s*['"]?(.+?)['"]?\\s*$/m);
+  if (m) {
+    const raw = m[1].trim();
+    if (raw && raw !== '__kenaz_core__' && isDir(raw)) {
+      process.stdout.write(JSON.stringify({ level: 'L1', result: raw }) + '\\n');
+      process.exit(0);
+    }
+  }
+} catch {}
+// L2: KENAZ_SOURCE_DIR
+const envDir = process.env.KENAZ_SOURCE_DIR || '';
+if (envDir && isDir(envDir)) {
+  process.stdout.write(JSON.stringify({ level: 'L2', result: envDir }) + '\\n');
+  process.exit(0);
+}
+// L3: auto-discover
+const auto = autoDiscover();
+if (auto) {
+  process.stdout.write(JSON.stringify({ level: 'L3', result: auto }) + '\\n');
+  process.exit(0);
+}
+// L4: projects.json is_core
+try {
+  const home = process.env.USERPROFILE || process.env.HOME || os.homedir();
+  const raw = fs.readFileSync(path.join(home, '.kenaz', 'projects.json'), 'utf8');
+  const data = JSON.parse(raw);
+  const core = (data.projects || []).find(p => p.is_core);
+  if (core && core.path && isDir(core.path)) {
+    process.stdout.write(JSON.stringify({ level: 'L4', result: core.path }) + '\\n');
+    process.exit(0);
+  }
+} catch {}
+process.stdout.write(JSON.stringify({ level: null, result: null }) + '\\n');
+`;
+    const probeFile = path.join(outsideDir, 'probe-l4.js');
+    writeFile(probeFile, probeCode);
+
+    // Empty tempdir for LOCALAPPDATA to block standard-install-location auto-discover
+    const emptyLocalAppData = mkTemp('rc-l4-localappdata');
+
+    const spawnEnv = Object.assign({}, process.env, {
+      KENAZ_SOURCE_DIR:  '',
+      HOME:              fakeHome,
+      USERPROFILE:       fakeHome,
+      LOCALAPPDATA:      emptyLocalAppData,
+      PROBE_PROJECT_PATH: outsideDir,
+    });
+
+    const res = spawnSync(process.execPath, [probeFile], {
+      cwd:         outsideDir,
+      env:         spawnEnv,
+      timeout:     8000,
+      encoding:    'utf8',
+      windowsHide: true,
+    });
+    if (res.error) throw new Error(`spawn failed: ${res.error.message}`);
+
+    let parsed;
+    try { parsed = JSON.parse(res.stdout.trim()); }
+    catch { throw new Error(`probe output not JSON: ${res.stdout.slice(0, 300)}\nstderr: ${res.stderr.slice(0, 300)}`); }
+
+    assert(
+      parsed.level === 'L4',
+      `[resolver=resolveCoreDir][fixture=projects-json][level=L4] ` +
+      `expected level=L4 (is_core fallback) but got level=${parsed.level}, result=${parsed.result}`
+    );
+    assertEqual(parsed.result, coreProject,
+      '[resolver=resolveCoreDir][fixture=projects-json][level=L4] ' +
+      'is_core entry should be returned as last-resort fallback');
+
+    fs.rmSync(emptyLocalAppData, { recursive: true, force: true });
+  } finally {
+    fs.rmSync(fakeHome,    { recursive: true, force: true });
+    fs.rmSync(coreProject, { recursive: true, force: true });
+    fs.rmSync(outsideDir,  { recursive: true, force: true });
+  }
+});
+
+// ══════════════════════════════════════════════════════════════════════════════
+//  SUITE 2 — resolveTasksDir priority chain  (task-api.js)
+// ══════════════════════════════════════════════════════════════════════════════
+
+suite('resolveTasksDir [.collaboration/core/task-api.js] priority chain');
+
+// Explicit tasksDir always wins
+test('[resolver=resolveTasksDir][level=L1] explicit tasksDir option wins over projectPath', () => {
+  const explicit = path.join(os.tmpdir(), `kenaz-explicit-tasks-${uid()}`);
+  const projectDir = mkTemp('td-l1-project');
+  try {
+    ensureDir(path.join(projectDir, '.kenaz', 'tasks'));
+    const result = resolveTasksDir({ tasksDir: explicit, projectPath: projectDir });
+    assert(result === explicit,
+      `[resolver=resolveTasksDir][level=L1] explicit tasksDir="${explicit}" should win, got "${result}"`);
+  } finally {
+    fs.rmSync(projectDir, { recursive: true, force: true });
+  }
+});
+
+// .kenaz/tasks/ beats .collaboration/tasks/ when projectPath provided
+test('[resolver=resolveTasksDir][level=L2a] .kenaz/tasks/ beats .collaboration/tasks/', () => {
+  const projectDir = mkTemp('td-l2a-project');
+  try {
+    const kenazTasks = path.join(projectDir, '.kenaz', 'tasks');
+    const collabTasks = path.join(projectDir, '.collaboration', 'tasks');
+    ensureDir(kenazTasks);
+    ensureDir(collabTasks);
+    const result = resolveTasksDir({ projectPath: projectDir });
+    assert(result === kenazTasks,
+      `[resolver=resolveTasksDir][fixture=kenaz-beats-collab][level=L2a] ` +
+      `.kenaz/tasks/ should win over .collaboration/tasks/, got "${result}"`);
+  } finally {
+    fs.rmSync(projectDir, { recursive: true, force: true });
+  }
+});
+
+// .collaboration/tasks/ returned when .kenaz/tasks/ absent
+test('[resolver=resolveTasksDir][level=L2b] .collaboration/tasks/ returned when .kenaz/tasks/ absent', () => {
+  const projectDir = mkTemp('td-l2b-project');
+  try {
+    const collabTasks = path.join(projectDir, '.collaboration', 'tasks');
+    ensureDir(collabTasks);
+    // No .kenaz/tasks/
+    const result = resolveTasksDir({ projectPath: projectDir });
+    assert(result === collabTasks,
+      `[resolver=resolveTasksDir][fixture=collab-only][level=L2b] ` +
+      `.collaboration/tasks/ should be returned when .kenaz/tasks/ absent, got "${result}"`);
+  } finally {
+    fs.rmSync(projectDir, { recursive: true, force: true });
+  }
+});
+
+// ══════════════════════════════════════════════════════════════════════════════
+//  SUITE 3 — resolveKenazPath priority chain  (phase-gate.js IIFE)
+// ══════════════════════════════════════════════════════════════════════════════
+//
+// resolveKenazPath locks CLI_PROJECT_PATH at require() time via an IIFE, so we
+// test it via an inline subprocess probe to avoid module-cache lock-in.
+//
+// Priority chain:
+//   L1  --project-path <path>  → <path>/.kenaz/...
+//   L2  cwd has .kenaz/        → cwd/.kenaz/...
+//   L3  BASE_DIR/.kenaz/...    (phase-gate's own project root)
+
+suite('resolveKenazPath [.specialist/tools/phase-gate.js IIFE] priority chain');
+
+// Inline probe: reimplements resolveKenazPath priority logic in isolation
+function makeKenazPathProbeCode(baseDir) {
+  return `
+'use strict';
+const fs = require('fs');
+const path = require('path');
+// Mirror of phase-gate.js resolveKenazPath / IIFE
+const BASE_DIR = ${JSON.stringify(baseDir)};
+let CLI_PROJECT_PATH = null;
+(function () {
+  const args = process.argv.slice(2);
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith('--project-path=')) {
+      CLI_PROJECT_PATH = path.resolve(args[i].slice('--project-path='.length));
+      return;
+    }
+    if (args[i] === '--project-path' && i + 1 < args.length) {
+      CLI_PROJECT_PATH = path.resolve(args[i + 1]);
+      return;
+    }
+  }
+}());
+function resolveKenazPath(...segments) {
+  if (CLI_PROJECT_PATH) return path.join(CLI_PROJECT_PATH, '.kenaz', ...segments);
+  const cwdPath = path.join(process.cwd(), '.kenaz', ...segments);
+  if (fs.existsSync(path.join(process.cwd(), '.kenaz'))) return cwdPath;
+  return path.join(BASE_DIR, '.kenaz', ...segments);
+}
+const resolved = resolveKenazPath('tasks');
+process.stdout.write(JSON.stringify({ resolved }) + '\\n');
+`;
+}
+
+test('[resolver=resolveKenazPath][level=L1] --project-path wins over cwd .kenaz/', () => {
+  const projectDir = mkTemp('kp-l1-cli');
+  const cwdDir     = mkTemp('kp-l1-cwd');
+  try {
+    // Both dirs have .kenaz/ but --project-path should win
+    ensureDir(path.join(projectDir, '.kenaz'));
+    ensureDir(path.join(cwdDir, '.kenaz'));
+    const probeFile = path.join(cwdDir, 'probe-kp.js');
+    writeFile(probeFile, makeKenazPathProbeCode(PROJECT_ROOT));
+
+    const res = spawnSync(
+      process.execPath,
+      [probeFile, '--project-path', projectDir],
+      { cwd: cwdDir, timeout: 6000, encoding: 'utf8', windowsHide: true }
+    );
+    if (res.error) throw new Error(`spawn: ${res.error.message}`);
+    const parsed = JSON.parse(res.stdout.trim());
+    const expected = path.join(projectDir, '.kenaz', 'tasks');
+    assert(normPath(parsed.resolved) === normPath(expected),
+      `[resolver=resolveKenazPath][level=L1] --project-path should win.\n` +
+      `    actual:   ${parsed.resolved}\n    expected: ${expected}`);
+  } finally {
+    fs.rmSync(projectDir, { recursive: true, force: true });
+    fs.rmSync(cwdDir,     { recursive: true, force: true });
+  }
+});
+
+test('[resolver=resolveKenazPath][level=L2] cwd .kenaz/ wins when no --project-path', () => {
+  const cwdDir = mkTemp('kp-l2-cwd');
+  try {
+    ensureDir(path.join(cwdDir, '.kenaz'));
+    const probeFile = path.join(cwdDir, 'probe-kp.js');
+    writeFile(probeFile, makeKenazPathProbeCode(PROJECT_ROOT));
+
+    const res = spawnSync(
+      process.execPath,
+      [probeFile],  // no --project-path
+      { cwd: cwdDir, timeout: 6000, encoding: 'utf8', windowsHide: true }
+    );
+    if (res.error) throw new Error(`spawn: ${res.error.message}`);
+    const parsed = JSON.parse(res.stdout.trim());
+    const expected = path.join(cwdDir, '.kenaz', 'tasks');
+    assert(normPath(parsed.resolved) === normPath(expected),
+      `[resolver=resolveKenazPath][level=L2] cwd .kenaz/ should win when no --project-path.\n` +
+      `    actual:   ${parsed.resolved}\n    expected: ${expected}`);
+  } finally {
+    fs.rmSync(cwdDir, { recursive: true, force: true });
+  }
+});
+
+test('[resolver=resolveKenazPath][level=L3] falls back to BASE_DIR/.kenaz/ when cwd has no .kenaz/', () => {
+  const cwdDir = mkTemp('kp-l3-cwd');
+  try {
+    // cwdDir has NO .kenaz/
+    const probeFile = path.join(cwdDir, 'probe-kp.js');
+    writeFile(probeFile, makeKenazPathProbeCode(PROJECT_ROOT));
+
+    const res = spawnSync(
+      process.execPath,
+      [probeFile],
+      { cwd: cwdDir, timeout: 6000, encoding: 'utf8', windowsHide: true }
+    );
+    if (res.error) throw new Error(`spawn: ${res.error.message}`);
+    const parsed = JSON.parse(res.stdout.trim());
+    const expected = path.join(PROJECT_ROOT, '.kenaz', 'tasks');
+    assert(normPath(parsed.resolved) === normPath(expected),
+      `[resolver=resolveKenazPath][level=L3] should fall back to BASE_DIR/.kenaz/.\n` +
+      `    actual:   ${parsed.resolved}\n    expected: ${expected}`);
+  } finally {
+    fs.rmSync(cwdDir, { recursive: true, force: true });
+  }
+});
+
+// ══════════════════════════════════════════════════════════════════════════════
+//  SUITE 4 — install.js bash wrapper priority chain  (Unix only)
+// ══════════════════════════════════════════════════════════════════════════════
+//
+// The inline node script embedded in the bash wrapper follows a 3-level chain:
+//   L1  project.yaml core_path (validated)
+//   L2  KENAZ_SOURCE_DIR env var (validated)
+//   L3  LOCALAPPDATA / ~/.local auto-discovery (no is_core fallback in bash wrapper)
+//
+// These tests execute the wrapper's node logic via a reconstructed probe script.
+// Windows: skipped — install.js generates bash scripts only meaningful on Unix.
+
+suite('install.js bash wrapper inline node script priority chain');
+
+if (process.platform === 'win32') {
+  process.stdout.write(
+    '  ⚠ bash-wrapper suite skipped on win32 — ' +
+    'the generated hook is a bash script; run on Linux/macOS CI to cover this suite.\n'
+  );
+} else {
+  // On Unix: extract the inline node -e script from install.js.
+  // The extraction uses a boundary-marker approach to handle embedded quotes reliably.
+  // The script is between `node -e "` and the final `" 2>/dev/null)` on its own line.
+  let WRAPPER_NODE_CODE = null;
+  try {
+    const installSrc = fs.readFileSync(
+      path.join(PROJECT_ROOT, '.collaboration', 'hooks', 'install.js'), 'utf8'
+    );
+    // Find the wrapperScript template literal and extract the node -e body
+    // by splitting on the known start/end sentinels in the source
+    const startMarker = 'CORE_PATH=$(node -e "\n';
+    const endMarker   = '" 2>/dev/null)';
+    const si = installSrc.indexOf(startMarker);
+    const ei = si >= 0 ? installSrc.indexOf(endMarker, si + startMarker.length) : -1;
+    if (si >= 0 && ei >= 0) {
+      const rawCode = installSrc.slice(si + startMarker.length, ei);
+      // Un-shell-escape: \\" → " and \\\\ → \\ in the extracted JS source
+      WRAPPER_NODE_CODE = rawCode
+        .replace(/\\"/g, '"')
+        .replace(/\\\\/g, '\\');
+    }
+  } catch { /* install.js not readable */ }
+
+  if (WRAPPER_NODE_CODE) {
+    // Write to a temp file (avoids -e quoting issues with multiline code)
+    const wrapperProbeFile = path.join(os.tmpdir(), `kenaz-bw-probe-${uid()}.js`);
+    fs.writeFileSync(wrapperProbeFile, WRAPPER_NODE_CODE, 'utf8');
+
+    test('[resolver=bash-wrapper][level=L1] project.yaml valid core_path wins', () => {
+      const projectDir = mkTemp('bw-l1-project');
+      const coreDir    = mkTemp('bw-l1-core');
+      try {
+        writeFile(
+          path.join(projectDir, '.kenaz', 'project.yaml'),
+          `name: test\ncore_path: "${fwdSlash(coreDir)}"\n`
+        );
+        const res = spawnSync(process.execPath, [wrapperProbeFile], {
+          cwd:         projectDir,
+          env:         Object.assign({}, process.env, { KENAZ_SOURCE_DIR: '' }),
+          timeout:     6000,
+          encoding:    'utf8',
+          windowsHide: true,
+        });
+        if (res.error) throw new Error(`spawn: ${res.error.message}`);
+        const result = res.stdout.trim();
+        assertEqual(result, coreDir,
+          '[resolver=bash-wrapper][fixture=project-yaml-valid][level=L1] ' +
+          'project.yaml core_path should win');
+      } finally {
+        fs.rmSync(projectDir, { recursive: true, force: true });
+        fs.rmSync(coreDir,    { recursive: true, force: true });
+      }
+    });
+
+    test('[resolver=bash-wrapper][level=L1→L2] sentinel in project.yaml → KENAZ_SOURCE_DIR wins', () => {
+      const projectDir = mkTemp('bw-l2-project');
+      const envDir     = mkTemp('bw-l2-env');
+      try {
+        writeFile(
+          path.join(projectDir, '.kenaz', 'project.yaml'),
+          `name: test\ncore_path: __kenaz_core__\n`
+        );
+        const res = spawnSync(process.execPath, [wrapperProbeFile], {
+          cwd:         projectDir,
+          env:         Object.assign({}, process.env, { KENAZ_SOURCE_DIR: envDir }),
+          timeout:     6000,
+          encoding:    'utf8',
+          windowsHide: true,
+        });
+        if (res.error) throw new Error(`spawn: ${res.error.message}`);
+        const result = res.stdout.trim();
+        assertEqual(result, envDir,
+          '[resolver=bash-wrapper][fixture=sentinel][level=L1→L2] ' +
+          '__kenaz_core__ sentinel should be skipped; KENAZ_SOURCE_DIR should win');
+      } finally {
+        fs.rmSync(projectDir, { recursive: true, force: true });
+        fs.rmSync(envDir,     { recursive: true, force: true });
+      }
+    });
+
+    // Cleanup probe file after tests (best-effort)
+    try { fs.unlinkSync(wrapperProbeFile); } catch { /* ignore */ }
+  } else {
+    process.stdout.write(
+      '  ⚠ bash-wrapper inline script not extracted from install.js — ' +
+      'skipping bash-wrapper priority tests (check startMarker/endMarker in install.js source)\n'
+    );
+  }
+}
+
+// ══════════════════════════════════════════════════════════════════════════════
+//  Summary
+// ══════════════════════════════════════════════════════════════════════════════
+
+const totalMs  = RESULTS.reduce((s, r) => s + r.ms, 0);
+const passed   = RESULTS.filter(r => r.status === 'pass').length;
+const failed   = RESULTS.filter(r => r.status === 'fail').length;
+
+process.stdout.write(
+  `\n─────────────────────────────────────────────────────\n` +
+  `resolver-priority.test  ${passed} passed, ${failed} failed  (${totalMs}ms total)\n`
+);
+
+if (failed > 0) {
+  process.stdout.write('Failures:\n');
+  RESULTS.filter(r => r.status === 'fail').forEach(r => {
+    process.stdout.write(`  ✗ [${r.suite}] ${r.name}\n    ${r.error}\n`);
+  });
+}
+
+// Emit JSON summary for CI / downstream consumers
+process.stdout.write(
+  JSON.stringify({ file: 'resolver-priority.test.js', passed, failed, totalMs, results: RESULTS }, null, 2) + '\n'
+);
+
+process.exit(failed > 0 ? 1 : 0);