karajan-code 2.18.1 → 2.19.1

package/packages/hu-board/src/zombie-reaper.js

@@ -0,0 +1,207 @@
+/**
+ * Zombie session reaper for the HU Board (board-polish #2,
+ * KJC dogfooding 2026-05-07).
+ *
+ * Why this exists
+ * ===============
+ *
+ * Sessions in the SQLite db can stay "in flight" forever when the
+ * orchestrator process dies between iterations: their `status` stays
+ * `coding` / `stalled` / `paused`, the UI keeps surfacing them as
+ * actionable, and `kj board start` weeks later still pops a
+ * "Karajan needs an answer" modal for a checkpoint nobody owns
+ * anymore.
+ *
+ * Concretely, on 2026-05-07 the user opened the board on a fresh
+ * `kj board start` and saw the popup of an HU from 2026-04-27 — 9
+ * days dead, status still `paused`. The fix per his explicit
+ * mandate:
+ *
+ *   "No puede quedarse nada zombie. Debe haber algun sistema que lo
+ *    compruebe al arrancar y mate esos zombies."
+ *
+ * Thresholds (per his decision in the same session):
+ *   - status in (coding | stalled) and >= 6h since updated_at  → reap
+ *   - status === paused and >= 24h since updated_at            → reap
+ *   - everything else                                          → skip
+ *
+ * What "reap" means: write `status: "failed"` BOTH to the DB row
+ * AND to the underlying `~/.karajan/sessions/<id>/session.json`,
+ * append a structured checkpoint of the form
+ *   { stage: 'zombie-reap', reason: <reason>, at: <iso> }
+ * so the audit trail survives. The session row stays in place
+ * (we don't DELETE — the user can still inspect what happened).
+ *
+ * Why update the JSON on disk too
+ * -------------------------------
+ *
+ * The board's `fullScan()` reads every session.json on startup and
+ * upserts the row, OVERWRITING any DB-only mutation. If the reaper
+ * only updated the DB, the next reboot would reset the status back
+ * to `paused`/`stalled` because the JSON still says so. Persisting
+ * to disk makes the reap permanent on the first reboot — the user
+ * sees the cleanup once, and never again.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+const DEFAULT_CODING_HOURS = 6;
+const DEFAULT_PAUSED_HOURS = 24;
+const CODING_LIKE_STATUSES = new Set(["coding", "stalled", "running", "in_progress"]);
+const PAUSED_STATUSES = new Set(["paused", "checkpoint", "awaiting_answer"]);
+
+/**
+ * Decide whether a single session row qualifies as zombie at `now`.
+ * Pure function — no I/O. Used by both the reaper itself and the
+ * unit tests.
+ *
+ * @param {{ id: string, status: string, updated_at?: string|null,
+ *           created_at?: string|null }} session
+ * @param {{ now: number, codingHours: number, pausedHours: number }} ctx
+ * @returns {{ zombie: boolean, reason?: string }}
+ */
+export function classifyZombie(session, ctx) {
+  if (!session || !session.status) return { zombie: false };
+  const status = String(session.status).toLowerCase();
+  // Reference timestamp: prefer updated_at (the daemon writes that on
+  // every checkpoint sync), fall back to created_at (in case the row
+  // was inserted but never touched again).
+  const refIso = session.updated_at || session.created_at;
+  if (!refIso) return { zombie: false };
+  const refTs = new Date(refIso).getTime();
+  if (Number.isNaN(refTs)) return { zombie: false };
+  const ageHours = (ctx.now - refTs) / 3_600_000;
+  if (ageHours <= 0) return { zombie: false };
+  if (CODING_LIKE_STATUSES.has(status) && ageHours >= ctx.codingHours) {
+    return { zombie: true, reason: `${status} ${ageHours.toFixed(1)}h inactive (>= ${ctx.codingHours}h)` };
+  }
+  if (PAUSED_STATUSES.has(status) && ageHours >= ctx.pausedHours) {
+    return { zombie: true, reason: `${status} ${ageHours.toFixed(1)}h inactive (>= ${ctx.pausedHours}h)` };
+  }
+  return { zombie: false };
+}
+
+/**
+ * Filter a list of session rows down to the zombie ones. Pure.
+ *
+ * @param {Array<object>} sessions
+ * @param {{ now?: number, codingHours?: number, pausedHours?: number }} [opts]
+ * @returns {Array<{ session: object, reason: string }>}
+ */
+export function findZombieSessions(sessions, opts = {}) {
+  const ctx = {
+    now: opts.now ?? Date.now(),
+    codingHours: opts.codingHours ?? DEFAULT_CODING_HOURS,
+    pausedHours: opts.pausedHours ?? DEFAULT_PAUSED_HOURS,
+  };
+  const out = [];
+  for (const session of sessions || []) {
+    const verdict = classifyZombie(session, ctx);
+    if (verdict.zombie) out.push({ session, reason: verdict.reason });
+  }
+  return out;
+}
+
+/**
+ * Append a `zombie-reap` checkpoint to a JSON-encoded checkpoints
+ * blob (the on-disk format). Returns the new JSON string.
+ *
+ * Defensive about malformed input: if the existing blob isn't a
+ * JSON array, replaces it with a fresh array containing the new
+ * entry — never throws.
+ */
+export function appendZombieCheckpoint(existingJson, reason, isoTimestamp) {
+  let arr = [];
+  if (existingJson) {
+    try {
+      const parsed = JSON.parse(existingJson);
+      if (Array.isArray(parsed)) arr = parsed;
+    } catch { /* fall through with empty arr */ }
+  }
+  arr.push({ stage: "zombie-reap", reason, at: isoTimestamp });
+  return JSON.stringify(arr);
+}
+
+/**
+ * Default location of the on-disk session JSON files. Delegates to
+ * db.js::getKjHome (KJC-TSK-0420): KARAJAN_HOME > KJ_HOME > VITEST > default.
+ * @returns {string}
+ */
+import { getKjHome } from "./db.js";
+export function getSessionsDir() {
+  return path.join(getKjHome(), "sessions");
+}
+
+/**
+ * Persist `status: "failed"` and the new zombie-reap checkpoint to
+ * the on-disk session.json. This stops the next `fullScan()` from
+ * resurrecting the zombi.
+ *
+ * Safe-by-default: if the file is missing, malformed, or the write
+ * fails, this returns `false` and the caller logs a warning. We
+ * never throw and we never block the daemon's startup.
+ *
+ * @param {string} sessionId
+ * @param {string} reason
+ * @param {string} reapedAtIso
+ * @param {{ sessionsDir?: string }} [opts]
+ * @returns {boolean} true when the file was rewritten successfully
+ */
+export function markSessionFailedOnDisk(sessionId, reason, reapedAtIso, opts = {}) {
+  const dir = opts.sessionsDir || getSessionsDir();
+  const file = path.join(dir, sessionId, "session.json");
+  let raw;
+  try { raw = fs.readFileSync(file, "utf8"); } catch { return false; }
+  let parsed;
+  try { parsed = JSON.parse(raw); } catch { return false; }
+  if (!parsed || typeof parsed !== "object") return false;
+  parsed.status = "failed";
+  parsed.updated_at = reapedAtIso;
+  parsed.checkpoints = Array.isArray(parsed.checkpoints) ? parsed.checkpoints : [];
+  parsed.checkpoints.push({ stage: "zombie-reap", reason, at: reapedAtIso });
+  try {
+    fs.writeFileSync(file, JSON.stringify(parsed, null, 2));
+    return true;
+  } catch { return false; }
+}
+
+/**
+ * Reap every zombie session in the DB AND in the underlying
+ * session.json files. Side-effecting. Returns the list of reaped
+ * sessions so the server can log them.
+ *
+ * @param {object} deps
+ * @param {object} deps.db        better-sqlite3 Database handle
+ * @param {object} [deps.opts]    threshold + sessionsDir overrides
+ * @param {Function} [deps.now]   () => number, for tests
+ * @returns {Array<{ id: string, status_before: string, reason: string, disk_persisted: boolean }>}
+ */
+export function reapZombieSessions({ db, opts = {}, now = () => Date.now() }) {
+  if (!db) return [];
+  const allSessions = db.prepare(
+    "SELECT id, status, updated_at, created_at, checkpoints FROM sessions WHERE status NOT IN ('failed', 'approved', 'cancelled', 'done')",
+  ).all();
+  const zombies = findZombieSessions(allSessions, { ...opts, now: now() });
+  if (zombies.length === 0) return [];
+  const update = db.prepare(
+    "UPDATE sessions SET status = 'failed', checkpoints = ?, updated_at = ? WHERE id = ?",
+  );
+  const reapedAt = new Date(now()).toISOString();
+  const reaped = [];
+  for (const { session, reason } of zombies) {
+    const newCheckpoints = appendZombieCheckpoint(session.checkpoints, reason, reapedAt);
+    update.run(newCheckpoints, reapedAt, session.id);
+    const diskPersisted = markSessionFailedOnDisk(session.id, reason, reapedAt, {
+      sessionsDir: opts.sessionsDir,
+    });
+    reaped.push({
+      id: session.id,
+      status_before: session.status,
+      reason,
+      disk_persisted: diskPersisted,
+    });
+  }
+  return reaped;
+}

package/src/audit/webperf-input.js

@@ -28,15 +28,12 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import os from "node:os";
 import { evaluateCwv, CWV_THRESHOLDS } from "../webperf/cwv-gate.js";
+import { getWebperfDir } from "../utils/paths.js";
 
-// Resolve per call — `os.homedir()` reads $HOME each time, so test
-// suites that override $HOME for hermetic tmp dirs work without
-// special re-imports.
-function webperfHome() {
-  return path.join(os.homedir(), ".karajan", "webperf");
-}
+// Delegated to src/utils/paths.js (KJC-TSK-0420) — respects
+// KARAJAN_HOME / KJ_HOME (with deprecation warning) / VITEST tmp.
+function webperfHome() { return getWebperfDir(); }
 
 function projectSlug(projectDir) {
   return path.basename(projectDir || process.cwd()).replaceAll(/[^a-zA-Z0-9_-]/g, "_");

package/src/brain/standby-store.js

@@ -14,15 +14,17 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import os from "node:os";
 import { writeJsonAtomicSync } from "../utils/atomic-write.js";
+import { resolveHome } from "../utils/paths.js";
 
 const FILENAME_RE = /^[a-zA-Z0-9._-]+\.json$/;
 
+// Delegates to the unified resolver. PR 3 of KJC-PCS-0047 switched
+// the default to `.karajan` — hibernated sessions now persist under
+// `~/.karajan/standby/`, migrated automatically from the legacy
+// `~/.kj/standby/` on the next `kj` invocation.
 function getKjHome() {
-  if (process.env.KJ_HOME) return process.env.KJ_HOME;
-  if (process.env.VITEST) return path.join(os.tmpdir(), `kj-vitest-${process.pid}-${Math.random().toString(36).slice(2, 10)}`, ".kj");
-  return path.join(os.homedir(), ".kj");
+  return resolveHome({ defaultSegment: ".karajan" });
 }
 
 export function standbyDir() {

package/src/checks/dir-setup.js

@@ -7,6 +7,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { STRATEGY } from "./types.js";
+import { getKarajanHome } from "../utils/paths.js";
 
 const REQUIRED_DIRS = [
   "", // ~/.karajan/
@@ -26,8 +27,9 @@ export function createKarajanDirsCheck() {
     strategy: STRATEGY.AUTO,
     describe: "Create missing ~/.karajan subdirectories",
     async detect() {
-      const home = os.homedir();
-      const root = path.join(home, ".karajan");
+      // KJC-TSK-0420: KARAJAN_HOME / KJ_HOME aware via getKarajanHome().
+      const root = getKarajanHome();
+      const home = os.homedir(); // still needed for path.relative() below
       const missing = [];
       for (const sub of REQUIRED_DIRS) {
         const full = sub ? path.join(root, sub) : root;
@@ -62,6 +64,40 @@ export function createKarajanDirsCheck() {
   };
 }
 
+/**
+ * Detect a populated legacy `~/.kj/` left over from before
+ * KJC-PCS-0047 PR 3. The auto-migrator (src/utils/home-migration.js)
+ * moves its contents to `~/.karajan/` on the next `kj` invocation,
+ * so the fix is simply "run any kj command". Severity is `warn`
+ * (informational) because the legacy dir does not break anything —
+ * it just won't get read by the board until the migration runs.
+ * @internal Exported for dynamic import from tests.
+ */
+export function createLegacyKjHomeCheck() {
+  return {
+    name: "legacy-kj-home",
+    label: "legacy ~/.kj/ directory",
+    strategy: STRATEGY.MANUAL,
+    describe: "Detect unmigrated ~/.kj/ left over from pre-2.19 layout",
+    async detect() {
+      const legacy = path.join(os.homedir(), ".kj");
+      try {
+        const entries = await fs.readdir(legacy);
+        if (entries.length === 0) return { ok: true, severity: "info", detail: "Empty legacy ~/.kj/" };
+        const marker = path.join(getKarajanHome(), ".kj-migrated.json"); // KJC-TSK-0420
+        try { await fs.access(marker); return { ok: true, severity: "info", detail: "Already migrated" }; }
+        catch { /* no marker, still pending */ }
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `~/.kj/ still has ${entries.length} entries; will be migrated on the next kj invocation`,
+          fix: "Run any kj command (e.g. `kj doctor`) — the migrator runs automatically",
+        };
+      } catch { return { ok: true, severity: "info", detail: "No legacy ~/.kj/" }; }
+    },
+  };
+}
+
 export function getDirSetupChecks() {
-  return [createKarajanDirsCheck()];
+  return [createKarajanDirsCheck(), createLegacyKjHomeCheck()];
 }

package/src/cli/register-pipeline.js

@@ -105,6 +105,7 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--brain <mode>", "Brain decisor: on|off (default: on). When off, only legacy flags drive routing.")
     .option("--skip-role <role...>", "Force one or more roles OFF regardless of triage (e.g. --skip-role tester security)")
     .option("--force-role <role...>", "Force one or more roles ON regardless of triage")
+    .option("--skip-spec-review", "Bypass the spec-reviewer pre-pipeline audit")
     .option("--dry-run", "Show what would be executed without running anything")
     .option("--json", "Output JSON only (no styled display)")
     .option("-q, --quiet", "Show only stage status lines, suppress raw agent output (default)")

package/src/cli/register-plan.js

@@ -40,6 +40,7 @@ export function registerPlan(program, { pkgVersion }) {
     // flags only if you explicitly want a fast / sketch plan.
     .option("--no-tests-synth", "Skip the tests-synthesizer pass that fills in missing acceptance_tests")
     .option("--no-plan-review", "Skip the high-level plan reviewer pass (gaps / deps / overlap / order)")
+    .option("--skip-spec-review", "Bypass the spec-reviewer pre-pipeline audit")
     .option("--quick", "Sketch mode — skip every quality pass after the initial planner call")
     .option("-y, --yes", "Skip the project-name prompt (use the auto-derived default).")
     .option("--no-interactive", "Force non-interactive mode (no prompts, use defaults).")

package/src/cli.js

@@ -12,6 +12,7 @@ import { registerSonar } from "./cli/register-sonar.js";
 import { registerStandby } from "./cli/register-standby.js";
 import { printUpdateNotice } from "./utils/update-check.js";
 import { printWelcomeScreen } from "./utils/welcome.js";
+import { migrateKjToKarajan } from "./utils/home-migration.js";
 
 const PKG_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../package.json");
 const PKG_VERSION = JSON.parse(readFileSync(PKG_PATH, "utf8")).version;
@@ -107,6 +108,18 @@ program.action(async (_opts, command) => {
   printWelcomeScreen({ version: PKG_VERSION, config });
 });
 
+// One-shot ~/.kj/ → ~/.karajan/ consolidation. Idempotent via marker
+// file; failures non-blocking. See src/utils/home-migration.js.
+// Static import — the migrator runs on every kj invocation, no
+// lazy-load benefit + the architectural dynamic-imports budget would
+// otherwise grow by one for a permanent caller.
+try {
+  await migrateKjToKarajan();
+} catch (err) {
+  // eslint-disable-next-line no-console
+  console.warn(`\x1b[33m[warn]\x1b[0m home migration skipped: ${err.message}`);
+}
+
 try {
   await program.parseAsync();
 } catch (error) {

package/src/commands/plan/generate.js

@@ -13,6 +13,7 @@ import { recommendModelsForHu, complexityFromTaskType } from "../../hu/model-rou
 import { withBrainRecovery } from "../../brain/with-brain-recovery.js";
 import { buildStandbyState } from "../../brain/standby-store.js";
 import { printResumeHint } from "../../utils/display/resume-hint.js";
+import { runSpecReview } from "../../spec-review/run-spec-review.js";
 import { formatPlan, formatHuTable } from "./_shared.js";
 
 /**
@@ -40,6 +41,20 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
     }
   }
 
+  // Spec-reviewer pre-planner audit (KJC-PCS-0048). Static import —
+  // role runs every invocation (modulo bypass); no lazy-load benefit.
+  const reviewResult = await runSpecReview({
+    spec: task, config, logger, flags,
+    askQuestion: json ? null : (typeof flags?.askQuestion === "function" ? flags.askQuestion : null),
+  });
+  if (!reviewResult.proceed) {
+    logger?.info?.("Aborted by user after spec review.");
+    return { ok: false, aborted: true, reason: "spec-review-cancelled" };
+  }
+  if (reviewResult.refined && reviewResult.finalSpec) {
+    task = reviewResult.finalSpec; // downstream runs the refined spec
+  }
+
   const plannerRole = resolveRole(config, "planner");
   await assertAgentsAvailable([plannerRole.provider]);
   runLog.logText(`[planner] provider=${plannerRole.provider}`);

package/src/commands/run.js

@@ -11,6 +11,7 @@ import { printResumeHint } from "../utils/display/resume-hint.js";
 import { resolveRole } from "../config.js";
 import { parseCardId } from "../planning-game/adapter.js";
 import { confirmCwd } from "../utils/cwd-confirm.js";
+import { runSpecReview } from "../spec-review/run-spec-review.js";
 
 function createCliAskQuestion(opts = {}) {
   const { sessionId = null } = opts;
@@ -163,9 +164,26 @@ export async function runCommandHandler({ task, config, logger, flags }) {
     }
 
     const askQuestion = createCliAskQuestion();
+
+    // Spec-reviewer pre-pipeline audit (KJC-PCS-0048). Runs BEFORE
+    // anything else — surfaces ambiguity / missing scope / missing AC
+    // and lets the user bail out cheap, before any tokens burn.
+    // Bypass with --skip-spec-review. Static import — the role runs
+    // on every kj invocation (modulo bypass), no lazy-load benefit.
+    const reviewResult = await runSpecReview({ spec: task, config, logger, askQuestion, flags });
+    if (!reviewResult.proceed) {
+      logger.info("Aborted by user after spec review.");
+      cleanupRegistry();
+      return { ok: false, aborted: true, reason: "spec-review-cancelled" };
+    }
+    // If the user refined the spec via [r]efine, downstream runs the
+    // REFINED text (not the original) so the pipeline acts on what the
+    // user actually approved.
+    const effectiveTask = reviewResult.refined && reviewResult.finalSpec ? reviewResult.finalSpec : task;
+
     let result;
     try {
-      result = await runFlow({ task: task, config, logger, flags, emitter, askQuestion, pgTaskId: pgCardId || null, pgProject: pgProject || null });
+      result = await runFlow({ task: effectiveTask, config, logger, flags, emitter, askQuestion, pgTaskId: pgCardId || null, pgProject: pgProject || null });
     } finally {
       // KJC-TSK-0396: limpia el registro pase lo que pase (éxito,
       // throw, o paused). Los handlers de SIGINT/SIGTERM/exit son

package/src/commands/webperf.js

@@ -9,16 +9,14 @@
 
 import fs from "node:fs/promises";
 import path from "node:path";
-import os from "node:os";
 import yaml from "js-yaml";
 import { runWebperfScan } from "../webperf/scanner.js";
 import { withCliRunLog } from "../utils/cli-run-log.js";
 
-// Resolve home each call so tests that override $HOME for hermetic
-// tmp dirs work without re-importing the module.
-function defaultReportDir() {
-  return path.join(os.homedir(), ".karajan", "webperf");
-}
+// Delegated to src/utils/paths.js (KJC-TSK-0420) — respects
+// KARAJAN_HOME / KJ_HOME / VITEST tmp / default.
+import { getWebperfDir } from "../utils/paths.js";
+function defaultReportDir() { return getWebperfDir(); }
 
 /**
  * Slug a project directory the same way audit/basal-cost.js and

package/src/config/role-resolver.js

@@ -49,7 +49,9 @@ function isModelCompatible(agent, model) {
 // Roles that inherit provider/model from the coder when not explicitly configured
 const CODER_INHERITED_ROLES = new Set([
   "planner", "refactorer", "solomon", "researcher", "tester", "security",
-  "impeccable", "triage", "discover", "architect", "audit", "hu_reviewer", "hu-reviewer"
+  "impeccable", "triage", "discover", "architect", "audit",
+  "hu_reviewer", "hu-reviewer",
+  "spec_reviewer", "spec-reviewer",
 ]);
 
 function resolveProvider(roleConfig, role, roles, legacyCoder, legacyReviewer) {

package/src/mcp/handlers/direct-handlers.js

@@ -47,6 +47,9 @@ function applySessionOverrides(a, roleKeys) {
 }
 
 export async function handlePlanDirect(a, server, extra) {
+  // KJC-PCS-0048 PR 3b: same `specReviewMode: skip` → skipSpecReview
+  // mapping as kj_run. Default "auto" keeps the reviewer enabled.
+  if (a.specReviewMode === "skip") a.skipSpecReview = true;
   const { normalizePlanArgs } = await import("../tool-arg-normalizers.js");
   const options = normalizePlanArgs(a);
   const config = await buildConfig(options, "plan");

package/src/mcp/handlers/run-handler.js

@@ -113,6 +113,11 @@ function collectRequiredProviders(config) {
 }
 
 export async function handleRunDirect(a, server, extra) {
+  // KJC-PCS-0048 PR 3b: respect specReviewMode without changing the
+  // existing handler contract. "skip" maps to the same flag the CLI
+  // honours; "auto" (default) leaves the reviewer enabled but the
+  // non-TTY runSpecReview path never blocks the pipeline.
+  if (a.specReviewMode === "skip") a.skipSpecReview = true;
   const config = await buildConfig(a);
   await assertNotOnBaseBranch(config, { allowForRun: true });
   const logger = createLogger(config.output.log_level, "mcp");

package/src/mcp/tools.js

@@ -113,7 +113,8 @@ export const tools = [
         domain: { type: "string", description: "Domain knowledge: inline text describing the project domain, or absolute path to a .md file. Auto-saved to .karajan/domains/ for the curator." },
         brain: { type: "string", enum: ["on", "off"], description: "Brain decisor: on|off. Controls whether intent-driven routing overrides pipeline flags." },
         forceRole: { type: "array", items: { type: "string" }, description: "Force roles ON regardless of triage (e.g. [\"security\"])" },
-        skipRole: { type: "array", items: { type: "string" }, description: "Force roles OFF regardless of triage (e.g. [\"tester\"])" }
+        skipRole: { type: "array", items: { type: "string" }, description: "Force roles OFF regardless of triage (e.g. [\"tester\"])" },
+        specReviewMode: { type: "string", enum: ["auto", "skip"], description: "Pre-pipeline spec-reviewer behaviour (KJC-PCS-0048). `auto` (default): the role runs, findings stream to the client via progress events; the pipeline continues regardless. `skip`: bypass the reviewer entirely (mirrors the --skip-spec-review CLI flag)." }
       }
     }
   },
@@ -245,7 +246,8 @@ export const tools = [
         coder: { type: "string", description: "Legacy alias for planner" },
         coderModel: { type: "string", description: "Legacy alias for plannerModel" },
         projectDir: { type: "string", description: "Absolute path to the project directory" },
-        kjHome: { type: "string" }
+        kjHome: { type: "string" },
+        specReviewMode: { type: "string", enum: ["auto", "skip"], description: "Pre-planner spec-reviewer behaviour (KJC-PCS-0048). `auto` (default): runs the reviewer, findings stream as progress, planner continues. `skip`: bypass entirely." }
       }
     }
   },

package/src/plan/plan-store.js

@@ -6,8 +6,8 @@
 
 import fs from "node:fs/promises";
 import path from "node:path";
-import os from "node:os";
 import { writeJsonAtomic } from "../utils/atomic-write.js";
+import { resolveHome } from "../utils/paths.js";
 import { generatePlanId, normaliseAlias } from "./plan-id.js";
 
 /**
@@ -38,33 +38,13 @@ async function handleCorruptPlanFile(filePath, error) {
 }
 import { isPlanV2, migratePlanV1toV2 } from "./plan-schema.js";
 
-// Per-process tmp dir for VITEST runs that forget to set KJ_HOME. We
-// memoise across calls so every helper in the same test process sees
-// the same root (mirrors what setting KJ_HOME explicitly would do)
-// without racing. The trailing `.kj` segment keeps semantic parity
-// with non-VITEST defaults so existing path assertions don't break.
-let _vitestKjHome = null;
-function vitestTmpKjHome() {
-  if (_vitestKjHome) return _vitestKjHome;
-  _vitestKjHome = path.join(
-    os.tmpdir(),
-    `kj-vitest-${process.pid}-${Math.random().toString(36).slice(2, 10)}`,
-    ".kj"
-  );
-  return _vitestKjHome;
-}
-
+// Delegates to the unified resolver in src/utils/paths.js. PR 3 of
+// KJC-PCS-0047 flipped the default from `.kj` to `.karajan` — plans
+// now live under `~/.karajan/plans/`. The migrator (src/utils/
+// home-migration.js) auto-moves legacy `~/.kj/plans/` content on the
+// next `kj` invocation, so existing users are not stranded.
 export function getKjHome() {
-  if (process.env.KJ_HOME) return process.env.KJ_HOME;
-  // VITEST guard — without this, a test that calls savePlan() drops
-  // fixture files into the developer's real `~/.kj/plans/` and the
-  // running HU Board's chokidar watcher ingests them as "real" plans
-  // (observed: 49 fake "Add auth" plans contaminating the user's
-  // board). Auto-isolate to a per-process tmp dir so accidental
-  // writes can't leak. Tests that NEED to assert against a known
-  // path should still set KJ_HOME explicitly.
-  if (process.env.VITEST) return vitestTmpKjHome();
-  return path.join(os.homedir(), ".kj");
+  return resolveHome({ defaultSegment: ".karajan" });
 }
 
 /**

package/src/prompts/spec-reviewer.js

@@ -0,0 +1,66 @@
+// Prompt builder for the `spec-reviewer` role (KJC-PCS-0048 PR 1).
+// Mirrors src/prompts/triage.js — project-level override at
+// `<projectDir>/.karajan/roles/spec-reviewer.md` is injected via `instructions`.
+
+const SUBAGENT_PREAMBLE = [
+  "IMPORTANT: You are running as a Karajan sub-agent.",
+  "Do NOT execute or plan the task. Do NOT mention Karajan.",
+  "Do NOT use any MCP tools. Your only job is to audit the user's spec.",
+].join(" ");
+
+const VALID_CATEGORIES = [
+  "ambiguity", "missing_scope", "missing_ac", "contradiction",
+  "stack", "assumptions", "out_of_scope",
+];
+
+const SCHEMA_HINT = JSON.stringify({
+  severity: "ok|info|warn|fail",
+  findings: [{
+    id: "F-001",
+    severity: "info|warn|fail",
+    category: VALID_CATEGORIES.join("|"),
+    message: "concrete description",
+    suggestion: "concrete sentence the user can paste",
+  }],
+  reasoning: "one or two sentences",
+}, null, 2);
+
+export function buildSpecReviewerPrompt({ spec, instructions } = {}) {
+  const sections = [SUBAGENT_PREAMBLE];
+  if (instructions) sections.push(instructions);
+  sections.push(
+    "You are the **Spec Reviewer** for Karajan Code.",
+    `Categories (pick one per finding): ${VALID_CATEGORIES.join(", ")}.`,
+    "Severity: `info` (nuance), `warn` (real gap), `fail` (unworkable). Top-level severity is the WORST of any finding (or `ok` if none).",
+    "Return JSON only:",
+    "```json", SCHEMA_HINT, "```",
+    "## Spec to audit", "```", String(spec || "").trim(), "```",
+  );
+  return sections.join("\n");
+}
+
+/**
+ * Build the refine prompt — used when the user picks `[r]efine`. The
+ * agent must rewrite the spec to fix the listed findings, returning
+ * ONLY the rewritten spec (no JSON, no preamble, no fence). The refine
+ * loop will persist this verbatim as `spec-v2.md`.
+ */
+export function buildSpecRefinerPrompt({ originalSpec, findings, instructions } = {}) {
+  const sections = [SUBAGENT_PREAMBLE];
+  if (instructions) sections.push(instructions);
+  const findingsBlock = (findings || []).map((f, i) => {
+    const idx = i + 1;
+    return `${idx}. [${f.severity}/${f.category}] ${f.message}${f.suggestion ? `\n   Fix: ${f.suggestion}` : ""}`;
+  }).join("\n");
+  sections.push(
+    "Your task: produce a rewritten version of the user's spec that addresses every finding listed below.",
+    "Output the rewritten spec verbatim — no JSON, no preamble, no markdown fences, no commentary.",
+    "Preserve the user's intent; do not invent new requirements or scope beyond the existing spec.",
+    "## Original spec", "```", String(originalSpec || "").trim(), "```",
+    "## Findings to address", findingsBlock || "(none — pass-through)",
+    "## Rewritten spec",
+  );
+  return sections.join("\n");
+}
+
+export { VALID_CATEGORIES };

package/src/roles/perf-role.js

@@ -20,7 +20,6 @@
 
 import fs from "node:fs/promises";
 import path from "node:path";
-import os from "node:os";
 import { BaseRole } from "./base-role.js";
 import { runWebperfScan } from "../webperf/scanner.js";
 
@@ -28,9 +27,10 @@ function projectSlug(projectDir) {
   return path.basename(projectDir || process.cwd()).replaceAll(/[^a-zA-Z0-9_-]/g, "_");
 }
 
-function defaultPersistDir() {
-  return path.join(os.homedir(), ".karajan", "webperf");
-}
+// Delegated to src/utils/paths.js (KJC-TSK-0420) — respects
+// KARAJAN_HOME / KJ_HOME / VITEST tmp / default.
+import { getWebperfDir } from "../utils/paths.js";
+function defaultPersistDir() { return getWebperfDir(); }
 
 async function persistResult(result, projectDir) {
   if (!result?.ok) return null;