karajan-code 2.19.0 → 2.19.1

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/paths.js

@@ -89,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.