karajan-code 2.18.1 → 2.19.1

package/src/roles/spec-reviewer-role.js

@@ -0,0 +1,106 @@
+// Spec Reviewer role (KJC-PCS-0048 PR 1). Runs BEFORE intent/triage/planner;
+// audits the user's spec and returns structured findings. Does NOT execute.
+
+import { AgentRole } from "./agent-role.js";
+import { buildSpecReviewerPrompt, buildSpecRefinerPrompt, VALID_CATEGORIES } from "../prompts/spec-reviewer.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
+
+const F_SEVS = new Set(["info", "warn", "fail"]);
+const T_SEVS = new Set(["ok", "info", "warn", "fail"]);
+const CATS = new Set(VALID_CATEGORIES);
+const ORDER = { ok: 0, info: 1, warn: 2, fail: 3 };
+
+function normalise(findings) {
+  if (!Array.isArray(findings)) return [];
+  return findings.map((f, i) => ({
+    id: typeof f?.id === "string" && f.id.trim() ? f.id.trim() : `F-${String(i + 1).padStart(3, "0")}`,
+    severity: F_SEVS.has(f?.severity) ? f.severity : "warn",
+    category: CATS.has(f?.category) ? f.category : "ambiguity",
+    message: String(f?.message || "").trim() || "(no description)",
+    suggestion: typeof f?.suggestion === "string" && f.suggestion.trim() ? f.suggestion.trim() : null,
+  }));
+}
+
+const worstOf = (findings) => findings.reduce((m, f) => (ORDER[f.severity] > ORDER[m] ? f.severity : m), "ok");
+
+export class SpecReviewerRole extends AgentRole {
+  constructor(opts) { super({ ...opts, name: "spec-reviewer" }); }
+
+  extractInput(input) {
+    if (typeof input === "string") return { spec: input, onOutput: null };
+    return {
+      spec: input?.spec || input?.task || this.context?.task || "",
+      onOutput: input?.onOutput || null,
+      sessionState: input?.sessionState || null,
+    };
+  }
+
+  async buildPrompt({ spec }) {
+    return { prompt: buildSpecReviewerPrompt({ spec, instructions: this.instructions }) };
+  }
+
+  parseOutput(raw) { return extractFirstJson(raw); }
+
+  buildSuccessResult(parsed, provider) {
+    const findings = normalise(parsed?.findings);
+    const declared = T_SEVS.has(parsed?.severity) ? parsed.severity : null;
+    const derived = worstOf(findings);
+    // Trust the worse of declared vs derived — agents sometimes report
+    // `severity: "ok"` while still listing fail-level findings.
+    const severity = !declared || ORDER[derived] > ORDER[declared] ? derived : declared;
+    return { severity, findings, reasoning: String(parsed?.reasoning || "").trim() || null, provider };
+  }
+
+  buildSummary(parsed) {
+    const findings = normalise(parsed?.findings);
+    if (findings.length === 0) return "Spec OK (no findings)";
+    return `Spec ${worstOf(findings)}: ${findings.length} finding${findings.length === 1 ? "" : "s"}`;
+  }
+
+  // Parse failures degrade to a soft warning so the pipeline never blocks.
+  handleParseNull(r, p) { return this.#degraded(r, p, "parse-null", "LLM output was unstructured"); }
+  handleParseError(e, r, p) { return this.#degraded(r, p, "parse-error", e?.message || "unknown"); }
+
+  /**
+   * Refine mode (KJC-PCS-0048 PR 3). Bypasses the JSON-only `execute()`
+   * flow: returns the LLM output verbatim as the rewritten spec, so the
+   * refine loop can persist it as `spec-v2.md`.
+   * @returns {Promise<{ ok:boolean, refinedSpec?:string, error?:string, provider:string, usage?:object }>}
+   */
+  async refineSpec({ spec, findings }) {
+    if (!this._initialized) await this.init({ task: spec });
+    const provider = this.resolveProvider();
+    const agent = this.createAgentInstance(provider);
+    const prompt = buildSpecRefinerPrompt({ originalSpec: spec, findings, instructions: this.instructions });
+    const result = await withBrainRecovery({
+      agent: { runTask: (a) => agent.runTask(a), provider },
+      taskArgs: { prompt, role: this.name },
+      role: this.name, provider, emitter: this.emitter, logger: this.logger,
+    });
+    if (!result.ok) {
+      return { ok: false, error: result.error || "refine failed", provider, usage: result.usage };
+    }
+    const refinedSpec = String(result.output || "").replace(/^```[a-z]*\n?|```$/g, "").trim();
+    if (!refinedSpec) return { ok: false, error: "empty refined spec", provider, usage: result.usage };
+    return { ok: true, refinedSpec, provider, usage: result.usage };
+  }
+
+  #degraded(agentResult, provider, reason, detail) {
+    return {
+      ok: true,
+      result: {
+        severity: "warn",
+        findings: [{
+          id: "F-DEG", severity: "warn", category: "assumptions",
+          message: `[spec-reviewer] degraded (${reason}): ${detail}`,
+          suggestion: "Re-run with --skip-spec-review if this keeps failing.",
+        }],
+        reasoning: "Spec reviewer could not parse the LLM output; treating as a soft warning.",
+        provider, degraded: true,
+      },
+      summary: `Spec reviewer degraded: ${reason}`,
+      usage: agentResult?.usage,
+    };
+  }
+}

package/src/spec-review/refine-loop.js

@@ -0,0 +1,58 @@
+// Refine loop for the spec-reviewer (KJC-PCS-0048 PR 3). Called from
+// run-spec-review.js when the user picks [r]efine. Asks the role for a
+// rewritten v2, persists v1.md / v2.md, opens $EDITOR for the user to
+// tweak, uses a SHA-256 hash diff to flag whether the v2 needs a fresh
+// review pass (user modified it) or can proceed as-is.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+
+const sha256 = (s) => crypto.createHash("sha256").update(String(s || ""), "utf8").digest("hex");
+
+function openEditor(filePath, { logger, openEditorFn = null } = {}) {
+  if (openEditorFn) return openEditorFn(filePath);
+  const raw = process.env.VISUAL || process.env.EDITOR || "vi"; // same precedence as src/commands/config.js
+  const parts = raw.split(/\s+/);
+  logger?.info?.(`Opening ${parts[0]} on ${filePath}`);
+  return spawnSync(parts[0], [...parts.slice(1), filePath], { stdio: "inherit" }).status === 0;
+}
+
+/**
+ * Single refine iteration. The outer loop in run-spec-review.js decides
+ * whether to re-invoke us based on the returned `hashChanged` flag
+ * (re-review the v2 because the user modified it) or accept the v2 as
+ * the final spec (`hashChanged === false`).
+ *
+ * @returns {Promise<{ok, refinedSpec?, hashChanged, error?, v2Path?}>}
+ */
+export async function runRefinePass({ spec, findings, role, projectDir, taskFile, logger, fs: fsOverride, openEditorFn }) {
+  const _fs = fsOverride || fs;
+  const refineRes = await role.refineSpec({ spec, findings });
+  if (!refineRes.ok) return { ok: false, error: refineRes.error || "refine failed", hashChanged: false };
+
+  let v2Path;
+  try {
+    const root = projectDir || process.cwd();
+    const ts = new Date().toISOString().replaceAll(/[:.]/g, "-");
+    const dir = path.join(root, ".reviews", `spec-review-${ts}`);
+    await _fs.mkdir(dir, { recursive: true });
+    await _fs.writeFile(path.join(dir, "spec-v1.md"), spec, "utf8");
+    v2Path = path.join(dir, "spec-v2.md");
+    await _fs.writeFile(v2Path, refineRes.refinedSpec, "utf8");
+    if (taskFile) {
+      // Mirror the v2 next to the user's --task-file so they find it
+      // without diving into .reviews/.
+      const p = path.parse(taskFile);
+      await _fs.writeFile(path.join(p.dir, `${p.name}.v2${p.ext || ".md"}`), refineRes.refinedSpec, "utf8").catch(() => {});
+    }
+  } catch (err) { return { ok: false, error: `persist failed: ${err.message}`, hashChanged: false }; }
+
+  const before = sha256(refineRes.refinedSpec);
+  openEditor(v2Path, { logger, openEditorFn });
+  let after;
+  try { after = await _fs.readFile(v2Path, "utf8"); }
+  catch (err) { return { ok: false, error: `read v2 failed: ${err.message}`, hashChanged: false }; }
+  return { ok: true, refinedSpec: after, hashChanged: before !== sha256(after), v2Path };
+}

package/src/spec-review/run-spec-review.js

@@ -0,0 +1,70 @@
+// Pre-pipeline orchestrator for the spec-reviewer (KJC-PCS-0048 PR 2).
+// Called from src/commands/run.js and src/commands/plan/generate.js
+// BEFORE the actual pipeline. Decides whether to proceed based on the
+// role's findings + the user's answer to the interactive prompt.
+// PR 2 only supports [c]ontinue / [x]cancel; refine loop lands in PR 3.
+
+import { SpecReviewerRole } from "../roles/spec-reviewer-role.js";
+import { printFindings } from "../utils/display/spec-findings.js";
+import { runRefinePass } from "./refine-loop.js";
+
+const MAX_REFINE_ITERATIONS = 5;
+
+export async function runSpecReview({ spec, config, logger, askQuestion, flags = {} }) {
+  // VITEST guard — pre-existing test suites (e.g. tests/commands/command-run.test.js)
+  // mock `runFlow` + `assertAgentsAvailable` but predate this role and have
+  // no need to exercise it. Auto-skip in vitest unless the test passes
+  // `flags.forceSpecReview: true` (the spec-review's own tests bypass via
+  // their vi.doMock of SpecReviewerRole and never reach this guard).
+  if (process.env.VITEST && !flags.forceSpecReview) return { proceed: true, skipped: true };
+  if (flags.skipSpecReview || config?.spec_reviewer?.enabled === false) {
+    return { proceed: true, skipped: true };
+  }
+  if (!spec || !String(spec).trim()) return { proceed: true, skipped: true };
+
+  const role = new SpecReviewerRole({ config, logger });
+  await role.init({ task: spec });
+
+  // Outer loop: review → prompt → optional refine → re-review (the
+  // refine path replaces `currentSpec` and we go around again).
+  let currentSpec = spec;
+  for (let iter = 0; iter < MAX_REFINE_ITERATIONS; iter += 1) {
+    const res = await role.execute({ spec: currentSpec });
+    if (!res.ok) {
+      logger?.warn?.(`[spec] reviewer failed: ${res.summary} — continuing without review`);
+      return { proceed: true, error: res.result?.error, finalSpec: currentSpec };
+    }
+    const { severity, findings } = res.result || {};
+    if (!findings || findings.length === 0 || severity === "ok") {
+      logger?.info?.(iter === 0 ? "✓ spec OK" : "✓ refined spec OK");
+      return { proceed: true, severity: "ok", findings: [], finalSpec: currentSpec, refined: iter > 0 };
+    }
+    printFindings(findings, severity);
+    if (!askQuestion) return { proceed: true, severity, findings, finalSpec: currentSpec };
+
+    const answer = await askQuestion(
+      `Spec review: ${findings.length} finding${findings.length === 1 ? "" : "s"} at severity ${severity}. [c]ontinue / [r]efine / [x]cancel? (default: continue)`,
+      { detail: { severity, findingCount: findings.length, categories: [...new Set(findings.map((f) => f.category))], iteration: iter + 1 } },
+    );
+    if (answer === null) return { proceed: false, cancelled: true, severity, findings };
+    const n = String(answer).trim().toLowerCase();
+    if (n.startsWith("x") || n === "cancel") return { proceed: false, cancelled: true, severity, findings };
+    if (n.startsWith("r") || n === "refine") {
+      const refine = await runRefinePass({
+        spec: currentSpec, findings, role,
+        projectDir: config?.projectDir, taskFile: flags.taskFile, logger,
+      });
+      if (!refine.ok) {
+        logger?.warn?.(`[spec] refine failed: ${refine.error} — proceeding with original spec`);
+        return { proceed: true, severity, findings, finalSpec: currentSpec };
+      }
+      currentSpec = refine.refinedSpec;
+      if (refine.hashChanged) continue; // user tweaked v2 → re-review
+      logger?.info?.("✓ refined spec accepted by user (no edits)");
+      return { proceed: true, severity: "ok", findings: [], finalSpec: currentSpec, refined: true };
+    }
+    return { proceed: true, severity, findings, finalSpec: currentSpec }; // continue
+  }
+  logger?.warn?.(`[spec] max refine iterations (${MAX_REFINE_ITERATIONS}) reached — proceeding with last spec`);
+  return { proceed: true, finalSpec: currentSpec, refined: true };
+}

package/src/utils/board-prompt-bridge.js

@@ -28,16 +28,15 @@
 
 import { mkdir, writeFile, readFile, unlink, stat } from "node:fs/promises";
 import { join } from "node:path";
-import { homedir } from "node:os";
 import { randomUUID } from "node:crypto";
 
 const POLL_INTERVAL_MS = 500;
 const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;          // 30 min
 
-function getPromptsDir() {
-  const home = process.env.KJ_HOME || join(homedir(), ".karajan");
-  return join(home, "prompts");
-}
+// Delegated to src/utils/paths.js so KARAJAN_HOME, KJ_HOME (with
+// deprecation warning), VITEST tmp and the default all share one
+// precedence chain — KJC-TSK-0420.
+import { getPromptsDir } from "./paths.js";
 
 function exists(path) {
   return stat(path).then(() => true, () => false);

package/src/utils/display/spec-findings.js

@@ -0,0 +1,44 @@
+// Pretty-printer for SpecReviewerRole findings (KJC-PCS-0048 PR 2).
+// Grouped by category, colours by severity, every finding gets its
+// `suggestion` printed below as the actionable fix-it line.
+
+const COLOURS = {
+  reset: "\x1b[0m", bold: "\x1b[1m", dim: "\x1b[2m",
+  cyan: "\x1b[36m", yellow: "\x1b[33m", red: "\x1b[31m", gray: "\x1b[90m",
+};
+
+const SEV_COLOUR = { info: COLOURS.cyan, warn: COLOURS.yellow, fail: COLOURS.red };
+const SEV_LABEL = { info: "INFO", warn: "WARN", fail: "FAIL" };
+
+function colour(severity, text) {
+  const c = SEV_COLOUR[severity] || COLOURS.gray;
+  return `${c}${text}${COLOURS.reset}`;
+}
+
+/**
+ * @param {Array<{id,severity,category,message,suggestion?}>} findings
+ * @param {"ok"|"info"|"warn"|"fail"} severity
+ * @param {object} [opts]
+ * @param {(line:string)=>void} [opts.write]  Defaults to `console.warn` (stderr).
+ */
+export function printFindings(findings, severity, opts = {}) {
+  const write = opts.write || ((line) => process.stderr.write(`${line}\n`));
+  if (!Array.isArray(findings) || findings.length === 0) return;
+
+  write("");
+  write(`${COLOURS.bold}Spec review — ${colour(severity, SEV_LABEL[severity] || severity.toUpperCase())}${COLOURS.reset} (${findings.length} finding${findings.length === 1 ? "" : "s"})`);
+
+  const byCat = new Map();
+  for (const f of findings) {
+    if (!byCat.has(f.category)) byCat.set(f.category, []);
+    byCat.get(f.category).push(f);
+  }
+  for (const [cat, items] of byCat) {
+    write(`${COLOURS.dim}── ${cat}${COLOURS.reset}`);
+    for (const f of items) {
+      write(`  ${colour(f.severity, "●")} ${COLOURS.bold}${f.id}${COLOURS.reset} ${f.message}`);
+      if (f.suggestion) write(`    ${COLOURS.dim}→${COLOURS.reset} ${f.suggestion}`);
+    }
+  }
+  write("");
+}

package/src/utils/garbage-collector.js

@@ -30,7 +30,7 @@
 
 import fs from "node:fs/promises";
 import path from "node:path";
-import os from "node:os";
+import { resolveHome } from "./paths.js";
 
 const FINAL_PLAN_STATUSES = new Set([
   // Terminal plan states the user explicitly opted into — retention applies.
@@ -39,13 +39,15 @@ const FINAL_PLAN_STATUSES = new Set([
 const KNOWN_PLAN_STATUSES = new Set([...FINAL_PLAN_STATUSES, "draft", "running"]);
 const FINAL_SESSION_STATUSES = new Set(["approved", "failed", "stopped", "rejected", "completed"]);
 
-function getKjHome() {
-  return process.env.KJ_HOME || path.join(os.homedir(), ".kj");
-}
-
+// Post-PR-3 of KJC-PCS-0047 both helpers point at the canonical
+// `~/.karajan/` root. `getKjHome` is kept as an alias of
+// `getKarajanHome` so legacy callers inside the file continue to
+// compile during the consolidation; both names resolve to the same
+// directory now that the layout is unified.
 function getKarajanHome() {
-  return process.env.KARAJAN_HOME || path.join(os.homedir(), ".karajan");
+  return resolveHome({ defaultSegment: ".karajan" });
 }
+const getKjHome = getKarajanHome;
 
 const DAY_MS = 24 * 60 * 60 * 1000;
 

package/src/utils/home-migration.js

@@ -0,0 +1,87 @@
+// One-shot ~/.kj/ → ~/.karajan/ home consolidation (PR 2 of KJC-PCS-0047).
+// Idempotent via `<target>/.kj-migrated.json`. Tarball backup under
+// `<target>/backup/`. `plans/`, `standby/`, `worktrees/` are moved
+// wholesale; `runs/` is merged with `.karajan/` winning on conflict.
+// Cross-device safe. Non-fatal: CLI bootstrap wraps in try/catch.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { execa } from "execa";
+
+const MARKER = ".kj-migrated.json";
+const MOVE_DIRS = ["plans", "standby", "worktrees"];
+
+async function readdirOrNull(dir) {
+  try { return await fs.readdir(dir); } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+async function moveChildren(src, dst, { mergeMode = false } = {}) {
+  const children = await readdirOrNull(src);
+  if (!children?.length) return 0;
+  await fs.mkdir(dst, { recursive: true });
+  let n = 0;
+  for (const c of children) {
+    const dstChild = path.join(dst, c);
+    if (mergeMode) {
+      try { await fs.access(dstChild); continue; } catch { /* no conflict */ }
+    }
+    const srcChild = path.join(src, c);
+    try { await fs.rename(srcChild, dstChild); } catch (err) {
+      if (err.code !== "EXDEV") throw err;
+      await fs.cp(srcChild, dstChild, { recursive: true });
+      await fs.rm(srcChild, { recursive: true, force: true });
+    }
+    n += 1;
+  }
+  await fs.rm(src, { recursive: true, force: true }).catch(() => {});
+  return n;
+}
+
+export async function migrateKjToKarajan({ dryRun = false, force = false } = {}) {
+  // VITEST guard — tests setting KJ_HOME would otherwise migrate against
+  // the developer's real HOME. Migrator's own tests pass `force: true`.
+  if (process.env.VITEST && !force) return { migrated: false, reason: "vitest-skip" };
+
+  const sourceDir = process.env.KJ_HOME || path.join(os.homedir(), ".kj");
+  const targetDir = process.env.KARAJAN_HOME || path.join(os.homedir(), ".karajan");
+
+  if (path.resolve(sourceDir) === path.resolve(targetDir)) {
+    return { migrated: false, reason: "same-path" };
+  }
+  const entries = await readdirOrNull(sourceDir);
+  if (!entries) return { migrated: false, reason: "source-missing" };
+  if (entries.length === 0) return { migrated: false, reason: "source-empty" };
+
+  await fs.mkdir(targetDir, { recursive: true });
+  const markerPath = path.join(targetDir, MARKER);
+  try { await fs.access(markerPath); return { migrated: false, reason: "already-migrated" }; }
+  catch { /* not present — proceed */ }
+
+  if (dryRun) return { migrated: false, reason: "dry-run", sourceDir, targetDir };
+
+  const backupDir = path.join(targetDir, "backup");
+  await fs.mkdir(backupDir, { recursive: true });
+  const ts = new Date().toISOString().replaceAll(/[:.]/g, "-");
+  const backupPath = path.join(backupDir, `kj-pre-migration-${ts}.tar.gz`);
+  await execa("tar", ["-czf", backupPath, "-C", path.dirname(sourceDir), path.basename(sourceDir)]);
+
+  const counts = {};
+  for (const sub of MOVE_DIRS) {
+    counts[sub] = await moveChildren(path.join(sourceDir, sub), path.join(targetDir, sub));
+  }
+  counts.runs = await moveChildren(path.join(sourceDir, "runs"), path.join(targetDir, "runs"), { mergeMode: true });
+
+  const marker = { version: 1, migrated_at: new Date().toISOString(), items_moved: counts, backup_path: backupPath, source_dir: sourceDir, target_dir: targetDir };
+  await fs.writeFile(markerPath, JSON.stringify(marker, null, 2));
+
+  const summary = Object.entries(counts).filter(([, n]) => n > 0).map(([k, n]) => `${n} ${k}`).join(" + ");
+  if (summary) {
+    // eslint-disable-next-line no-console
+    console.warn(`\x1b[33m[warn]\x1b[0m Migrated ${summary} from ${sourceDir} to ${targetDir} (backup: ${backupPath})`);
+  }
+  return { migrated: true, counts, backupPath, marker };
+}

package/src/utils/paths.js

@@ -1,32 +1,85 @@
 import os from "node:os";
 import path from "node:path";
 
-// Per-process tmp dir for VITEST runs that forget to set KJ_HOME. Same
-// rationale as src/plan/plan-store.js — without this, tests that use
-// real session/board paths leak files into the developer's real
-// `~/.karajan/` and pollute the HU Board's SQLite DB. Memoised so
-// every helper in the same process agrees on the path. The trailing
-// segment is `.karajan` to keep semantic parity with non-VITEST
-// defaults (existing tests assert paths contain ".karajan/...").
-let _vitestKarajanHome = null;
-function vitestTmpKarajanHome() {
-  if (_vitestKarajanHome) return _vitestKarajanHome;
-  _vitestKarajanHome = path.join(
+// Per-process vitest root. We memoise the *root* (not the suffixed
+// `.karajan` / `.kj` path) so callers with different legacy defaults
+// — plan-store wants `.kj`, db.js wants `.karajan` — can share one
+// random tmp prefix per test run without colliding.
+let _vitestRoot = null;
+function vitestRoot() {
+  if (_vitestRoot) return _vitestRoot;
+  _vitestRoot = path.join(
     os.tmpdir(),
-    `karajan-vitest-${process.pid}-${Math.random().toString(36).slice(2, 10)}`,
-    ".karajan"
+    `karajan-vitest-${process.pid}-${Math.random().toString(36).slice(2, 10)}`
   );
-  return _vitestKarajanHome;
+  return _vitestRoot;
 }
 
-export function getKarajanHome() {
+function vitestTmpHome(defaultSegment) {
+  return path.join(vitestRoot(), defaultSegment);
+}
+
+// One-shot warning so users with KJ_HOME set in their shell rcfile do
+// not get spammed once per `kj` invocation. Reset across processes,
+// which is the granularity that matters for a humans-reading-stderr
+// audience.
+let _kjHomeWarned = false;
+function emitKjHomeDeprecationWarning() {
+  if (_kjHomeWarned) return;
+  _kjHomeWarned = true;
+  // eslint-disable-next-line no-console
+  console.warn(
+    "\x1b[33m[warn]\x1b[0m KJ_HOME is deprecated, rename to KARAJAN_HOME (KJ_HOME will be removed in a future release)"
+  );
+}
+
+/**
+ * Unified resolver for Karajan's HOME-level storage root. Used by every
+ * helper that previously rolled its own `getKjHome()` with subtly
+ * different defaults and VITEST handling.
+ *
+ * Precedence (highest first):
+ *   1. KARAJAN_HOME env var — explicit, no warning
+ *   2. KJ_HOME env var      — explicit, prints deprecation warning once
+ *   3. VITEST tmp dir       — auto-isolation under `os.tmpdir()/karajan-vitest-<pid>-<rand>/<defaultSegment>`
+ *   4. `~/<defaultSegment>` — production default
+ *
+ * Callers pass `defaultSegment` so we can preserve `.kj` for legacy
+ * paths (plan-store, standby-store) and `.karajan` for the canonical
+ * root, until PR 3 unifies the defaults too.
+ *
+ * @param {object} [options]
+ * @param {string} [options.defaultSegment=".karajan"]  HOME subdir name
+ * @returns {string} absolute path
+ */
+export function resolveHome({ defaultSegment = ".karajan" } = {}) {
+  if (process.env.KARAJAN_HOME) {
+    return path.resolve(process.env.KARAJAN_HOME);
+  }
   if (process.env.KJ_HOME) {
+    emitKjHomeDeprecationWarning();
     return path.resolve(process.env.KJ_HOME);
   }
   if (process.env.VITEST) {
-    return vitestTmpKarajanHome();
+    return vitestTmpHome(defaultSegment);
   }
-  return path.join(os.homedir(), ".karajan");
+  return path.join(os.homedir(), defaultSegment);
+}
+
+/**
+ * Canonical Karajan home (`~/.karajan` by default). Every helper that
+ * used to roll its own `getKjHome()` now goes through this one — see
+ * KJC-PCS-0047 PR 3 for the consolidation.
+ */
+export function getKarajanHome() {
+  return resolveHome({ defaultSegment: ".karajan" });
+}
+
+// Test-only export. Tests that depend on observing the deprecation
+// warning being emitted exactly once need to reset the latch between
+// cases.
+export function __resetKjHomeWarningForTests() {
+  _kjHomeWarned = false;
 }
 
 export function getSessionRoot() {
@@ -36,3 +89,18 @@ export function getSessionRoot() {
 export function getSonarComposePath() {
   return path.join(getKarajanHome(), "docker-compose.sonar.yml");
 }
+
+/** Webperf cache: `<karajan-home>/webperf/` — KJC-TSK-0420. */
+export function getWebperfDir() {
+  return path.join(getKarajanHome(), "webperf");
+}
+
+/** Run-registry: `<karajan-home>/runs/` — KJC-TSK-0420. */
+export function getRunsDir() {
+  return path.join(getKarajanHome(), "runs");
+}
+
+/** Board prompt bridge: `<karajan-home>/prompts/` — KJC-TSK-0420. */
+export function getPromptsDir() {
+  return path.join(getKarajanHome(), "prompts");
+}

package/src/utils/run-registry.js

@@ -19,16 +19,16 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import os from "node:os";
 import { writeJsonAtomicSync } from "./atomic-write.js";
+import { getRunsDir } from "./paths.js";
 
 /**
  * Directorio raíz donde viven los registros de run.
- * Honra `KJ_HOME` para tests y setups custom.
+ * Delega en `getRunsDir()` (KJC-TSK-0420) — respeta KARAJAN_HOME,
+ * KJ_HOME (con warning de deprecación), VITEST tmp y default.
  */
 export function runsDir() {
-  const home = process.env.KJ_HOME || path.join(os.homedir(), ".karajan");
-  return path.join(home, "runs");
+  return getRunsDir();
 }
 
 /**

package/templates/roles/spec-reviewer.md

@@ -0,0 +1,38 @@
+You are the **Spec Reviewer**. You run BEFORE every other role. You audit the
+user's spec (prompt or `.md`) for deficiencies. You do NOT execute or plan.
+
+## Categories (every finding gets exactly one)
+
+- **ambiguity** — words without a concrete metric ("better", "clean", "fast").
+- **missing_scope** — no boundary of what should and should not be touched.
+- **missing_ac** — no acceptance criteria; nothing to verify against.
+- **contradiction** — two requirements that cannot both be satisfied.
+- **stack** — no tech stack hint when one is required.
+- **assumptions** — depends on unstated context.
+- **out_of_scope** — asks for things outside what Karajan can do.
+
+## Severity
+
+`info` (nuance), `warn` (real gap), `fail` (unworkable). Top-level `severity`
+is the WORST of any finding, or `ok` if findings is empty.
+
+## Output (JSON, nothing else)
+
+```json
+{
+  "severity": "ok|info|warn|fail",
+  "findings": [
+    {
+      "id": "F-001",
+      "severity": "info|warn|fail",
+      "category": "ambiguity|missing_scope|missing_ac|contradiction|stack|assumptions|out_of_scope",
+      "message": "quote the offending phrase verbatim when possible",
+      "suggestion": "a sentence the user can paste into the spec"
+    }
+  ],
+  "reasoning": "one or two sentences summarising the verdict"
+}
+```
+
+Direct, accionable. No moralising. `suggestion` must be concrete (a paste-able
+sentence), not vague advice.