karajan-code 4.70.4 → 5.0.1

package/src/utils/main-checkout.js

@@ -0,0 +1,53 @@
+/**
+ * The main checkout of the repo a dir belongs to: lanes and plans hang from it, never from a
+ * lane (#2566). Not the Sentinel's lane identity (ADR 0002). Outside git, the dir unchanged.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+// null only for "not a git repository"; any other git failure is loud, never a silent nested lane.
+const gitOrNull = (args, cwd) => {
+  // A git hook exports GIT_DIR & co: left in, they would override `cwd` and answer for the wrong repo.
+  const env = { ...process.env };
+  for (const name of ["GIT_DIR", "GIT_WORK_TREE", "GIT_COMMON_DIR", "LANGUAGE"]) delete env[name];
+  env.LC_ALL = "C"; // the stderr check below reads git's English message (KJC-BUG-0409)
+  try {
+    return execFileSync("git", args, { cwd, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+  } catch (err) {
+    if (/not a git repository/i.test(String(err.stderr))) return null;
+    throw new Error(`cannot resolve the main checkout of ${cwd}: ${String(err.stderr || err.message).trim()}`, { cause: err });
+  }
+};
+
+const mains = new Map(); // two git spawns per lookup, and plan list/load loops ask once per plan
+export const mainCheckout = (dir) => mains.get(dir) ?? mains.set(dir, resolveMain(dir)).get(dir);
+
+function resolveMain(dir) {
+  const out = gitOrNull(["rev-parse", "--path-format=absolute", "--git-common-dir", "--is-bare-repository"], dir);
+  if (out === null) return dir;
+  const [common, bare] = out.split("\n");
+  if (bare === "true") throw new Error(`${dir} belongs to a bare repository: kj lanes need a main checkout`);
+  // The main checkout is the dir whose `.git` IS the common dir or a file pointing at it. Git
+  // records no path back to it, so the candidates are the ancestors of the toplevel (lanes live
+  // under it; --separate-git-dir, submodules) and the common dir's parent (a lane beside it).
+  const top = gitOrNull(["rev-parse", "--show-toplevel"], dir);
+  const candidates = [];
+  for (let up = top; path.dirname(up) !== up; up = path.dirname(up)) candidates.push(up);
+  const found = [...candidates, path.dirname(common)].find((c) => dotGitIs(path.join(c, ".git"), common));
+  if (!found) {
+    throw new Error(`cannot find the main checkout of ${dir}: its git dir is separate and the worktree sits outside the checkout`);
+  }
+  return found;
+}
+
+const GITDIR_PREFIX = "gitdir:";
+const dotGitIs = (dotGit, common) => {
+  try {
+    if (fs.statSync(dotGit).isDirectory()) return fs.realpathSync(dotGit) === common;
+    const line = fs.readFileSync(dotGit, "utf8").split("\n").find((l) => l.startsWith(GITDIR_PREFIX));
+    return line !== undefined && fs.realpathSync(path.resolve(path.dirname(dotGit), line.slice(GITDIR_PREFIX.length).trim())) === common;
+  } catch {
+    return false; // no ".git" here: keep climbing
+  }
+};

package/src/utils/qmd-collection.js

@@ -2,7 +2,9 @@ import path from "node:path";
 import { existsSync, statSync } from "node:fs";
 import { runCommand } from "./process.js";
 
-export const QMD_DEFAULT_PATHS = ["docs", ".reviews", ".karajan/plans"];
+// ADR 0032: the wiki indexes what travels with the project, so a whole team gets the same one:
+// the docs and the plans shared with `kj plan share` (private plans stay out of it).
+export const QMD_DEFAULT_PATHS = ["docs", ".karajan-shared/plans"];
 
 export function projectSlug(projectDir) {
   const base = path.basename(path.resolve(projectDir));

package/src/utils/welcome.js

@@ -10,11 +10,11 @@ const A = {
 };
 
 const QUICK_START = [
-  ["kj run <task>",  "Run the full coder+reviewer pipeline"],
   ["kj init",        "Initialize config and setup"],
+  ["kj hu add",      "Put a piece of work on the board before it starts"],
+  ["kj review --staged", "Have another AI review the diff you are about to commit"],
+  ["kj board start", "Open the HU board and its governance view"],
   ["kj doctor",      "Check environment and agent availability"],
-  ["kj status",      "Show pipeline dashboard"],
-  ["kj report",      "Show latest session report"],
 ];
 
 /**

package/templates/{skills → atril/commands}/kj-architect.md

@@ -1,3 +1,8 @@
+---
+name: kj-architect
+description: "Architecture Design"
+kind: command
+---
 # kj-architect — Architecture Design
 
 Analyze the task and propose an architecture before implementation.

package/templates/{skills → atril/commands}/kj-audit.md

@@ -1,3 +1,8 @@
+---
+name: kj-audit
+description: "Codebase Health Audit"
+kind: command
+---
 # kj-audit — Codebase Health Audit
 
 Analyze the current codebase for security, code quality, performance, architecture, and testing issues. This is a READ-ONLY analysis — do not modify any files.

package/templates/{skills → atril/commands}/kj-board.md

@@ -1,3 +1,8 @@
+---
+name: kj-board
+description: "HU Board Dashboard"
+kind: command
+---
 # kj-board — HU Board Dashboard
 
 Manage the Karajan HU Board for visualizing user stories and sessions.

package/templates/{skills → atril/commands}/kj-code.md

@@ -1,3 +1,8 @@
+---
+name: kj-code
+description: "Coder with Guardrails"
+kind: command
+---
 # kj-code — Coder with Guardrails
 
 Implement the task with TDD methodology and built-in quality checks.

package/templates/{skills → atril/commands}/kj-csv-transform.md

@@ -1,3 +1,8 @@
+---
+name: kj-csv-transform
+description: "CSV & Data Transformation"
+kind: command
+---
 # kj-csv-transform — CSV & Data Transformation
 
 Transform, validate, and process CSV and tabular data files.

package/templates/{skills → atril/commands}/kj-data-report.md

@@ -1,3 +1,8 @@
+---
+name: kj-data-report
+description: "Data Report Generation"
+kind: command
+---
 # kj-data-report — Data Report Generation
 
 Generate structured data reports with clear findings, methodology, and recommendations.

package/templates/{skills → atril/commands}/kj-discover.md

@@ -1,3 +1,8 @@
+---
+name: kj-discover
+description: "Gap Detection"
+kind: command
+---
 # kj-discover — Gap Detection
 
 Analyze the task for gaps, ambiguities, and missing information BEFORE coding.

package/templates/{skills → atril/commands}/kj-rag-query.md

@@ -1,3 +1,8 @@
+---
+name: kj-rag-query
+description: "Query Project RAG index"
+kind: command
+---
 # kj-rag-query — Query Project RAG index
 
 Query the Project RAG (vector store + embedder) and return the top-K most relevant chunks of the indexed project: plans, onboarding briefs, and (optionally) source code.

package/templates/{skills → atril/commands}/kj-review.md

@@ -1,3 +1,8 @@
+---
+name: kj-review
+description: "Code Review with Quality Gates"
+kind: command
+---
 # kj-review — Code Review with Quality Gates
 
 Review the current changes against task requirements and quality standards.

package/templates/{skills → atril/commands}/kj-security.md

@@ -1,3 +1,8 @@
+---
+name: kj-security
+description: "Security Audit"
+kind: command
+---
 # kj-security — Security Audit
 
 Perform a security audit on the current changes.

package/templates/{skills → atril/commands}/kj-sonar.md

@@ -1,3 +1,8 @@
+---
+name: kj-sonar
+description: "Static Analysis"
+kind: command
+---
 # kj-sonar — Static Analysis
 
 Run SonarQube/SonarCloud analysis and fix any issues found.

package/templates/{skills → atril/commands}/kj-sql-analysis.md

@@ -1,3 +1,8 @@
+---
+name: kj-sql-analysis
+description: "SQL Analysis & Generation"
+kind: command
+---
 # kj-sql-analysis — SQL Analysis & Generation
 
 Generate and review SQL queries with a focus on correctness, performance, and security.

package/templates/{skills → atril/commands}/kj-test.md

@@ -1,3 +1,8 @@
+---
+name: kj-test
+description: "Test Quality Audit"
+kind: command
+---
 # kj-test — Test Quality Audit
 
 Evaluate test coverage and quality for the current changes.

package/packages/hu-board/public/utils/run-launcher.js

@@ -1,169 +0,0 @@
-// KJC-TSK-0501 step 8f/8 — Preflight gate + run launcher.
-//
-// Classic script (no exports). Loaded by index.html before app.js so the
-// top-level `function`/`let` declarations are hoisted into the shared
-// realm and the inline handlers in app.js (and elsewhere) resolve
-// `runProject` / `confirmRunWithPreflight` via that hoisting.
-//
-// Globals consumed from earlier scripts / app.js:
-//   - esc()                  (utils/formatters.js)
-//   - ensureDialog()         (app.js)
-//   - showError()            (utils/modals.js)
-//   - renderBoard()          (app.js)
-//   - openLogViewer()        (utils/log-panel.js)
-//   - lastLaunchedPlanId     (mutable in app.js — assignment crosses
-//                             scripts transparently)
-//   - lastOpenedLog          (mutable in app.js — same)
-
-// ---- Preflight panel + safety modal ----
-//
-// Goal: when a non-technical user opens a project, they should see at
-// a glance whether the environment is ready (git initialised, remote
-// configured, agents installed, Node version, etc.). Each missing
-// item is rendered with a plain-Spanish "consequence" so the user
-// understands what's at stake.
-//
-// The panel doubles as the gate for ▶ Run plan / ▶ Run HU: if any
-// blocker (status:fail with blocking:true) is present, we refuse to
-// launch. If only warnings are present, we open a confirm modal
-// listing them and require an explicit "Lanzar de todos modos".
-
-let preflightCache = null;     // memoise per-render so the modal can re-use what the panel already fetched
-
-async function fetchPreflight(projectId) {
-  try {
-    const r = await fetch(`/api/projects/${encodeURIComponent(projectId)}/preflight`);
-    if (!r.ok) return null;
-    return await r.json();
-  } catch { return null; }
-}
-
-function preflightStatusIcon(status) {
-  if (status === 'ok') return '✓';
-  if (status === 'warn') return '⚠';
-  if (status === 'fail') return '✗';
-  return 'ℹ';
-}
-function preflightStatusColor(status) {
-  if (status === 'ok') return 'var(--color-green)';
-  if (status === 'warn') return 'var(--color-yellow,#eab308)';
-  if (status === 'fail') return 'var(--color-red,#ef4444)';
-  return 'var(--text-muted)';
-}
-
-/**
- * Pre-run safety modal. Returns true if the user wants to proceed,
- * false to cancel. Call BEFORE invoking the run endpoint.
- *
- * Behaviour:
- *   - All green → returns true immediately (no modal).
- *   - Blockers present → modal explains them in plain Spanish; only
- *     "Cancelar" button (no proceed-anyway) because blockers are
- *     known to break the run.
- *   - Only warnings → modal lists them with their consequences and
- *     offers "Cancelar" or "Lanzar de todos modos" (red button so
- *     the user notices they're accepting risk).
- */
-async function confirmRunWithPreflight(projectId) {
-  const data = preflightCache || await fetchPreflight(projectId);
-  if (!data) return true;             // can't fetch → don't block the user
-  const blockers = data.blockers || [];
-  const warnings = data.warnings || [];
-  if (blockers.length === 0 && warnings.length === 0) return true;
-
-  return await new Promise((resolve) => {
-    const dlg = document.getElementById('app-dialog') || ensureDialog();
-    const isBlocked = blockers.length > 0;
-    const headerColor = isBlocked ? 'var(--color-red,#ef4444)' : 'var(--color-yellow,#eab308)';
-    const allItems = [...blockers, ...warnings];
-    dlg.innerHTML = `
-      <div style="padding:14px 18px;border-bottom:1px solid var(--border);font-weight:700;display:flex;align-items:center;gap:10px;background:${headerColor};color:#000;">
-        <span style="font-size:1.2rem;">${isBlocked ? '✗' : '⚠'}</span>
-        <span>${isBlocked ? 'No se puede lanzar — falta algo crítico' : 'Atención antes de lanzar'}</span>
-      </div>
-      <div style="padding:14px 18px;max-height:60vh;overflow:auto;">
-        <p style="margin:0 0 10px;font-size:0.9rem;color:var(--text);">
-          ${isBlocked
-            ? 'Se detectaron problemas bloqueantes que impedirán que Karajan funcione correctamente:'
-            : 'Se detectaron avisos. Karajan puede ejecutarse, pero con limitaciones:'}
-        </p>
-        <ul style="list-style:none;padding:0;margin:0;display:flex;flex-direction:column;gap:8px;">
-          ${allItems.map((c) => `
-            <li style="padding:8px 10px;background:var(--bg-primary);border-left:3px solid ${preflightStatusColor(c.status)};border-radius:var(--radius-sm);">
-              <div style="font-weight:600;color:var(--text);font-size:0.85rem;">
-                ${preflightStatusIcon(c.status)} ${esc(c.label)} — <span style="color:var(--text-muted);font-weight:400;">${esc(c.detail || '')}</span>
-              </div>
-              ${c.consequence ? `<div style="font-size:0.8rem;color:var(--text);margin-top:4px;">${esc(c.consequence)}</div>` : ''}
-            </li>
-          `).join('')}
-        </ul>
-      </div>
-      <div style="padding:12px 18px;border-top:1px solid var(--border);display:flex;gap:8px;justify-content:flex-end;">
-        <button id="preflight-cancel" style="padding:8px 16px;background:var(--bg-primary);border:1px solid var(--border);color:var(--text);border-radius:var(--radius-sm);cursor:pointer;">Cancelar</button>
-        ${isBlocked ? '' : `<button id="preflight-proceed" style="padding:8px 16px;background:var(--color-red,#ef4444);border:none;color:#fff;border-radius:var(--radius-sm);cursor:pointer;font-weight:600;">Lanzar de todos modos</button>`}
-      </div>
-    `;
-    if (typeof dlg.showModal === 'function' && !dlg.open) dlg.showModal();
-    const cancel = dlg.querySelector('#preflight-cancel');
-    const proceed = dlg.querySelector('#preflight-proceed');
-    const close = (val) => { try { dlg.close(); } catch { /* ignore */ } resolve(val); };
-    cancel?.addEventListener('click', () => close(false), { once: true });
-    proceed?.addEventListener('click', () => close(true), { once: true });
-    dlg.addEventListener('close', () => resolve(false), { once: true });
-  });
-}
-
-async function runProject(projectId) {
-  try {
-    const res = await fetch(`/api/projects/${encodeURIComponent(projectId)}/run`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({}),
-    });
-    if (!res.ok) {
-      if (res.status === 404) {
-        await showError(
-          'The board server does not recognise the "run" endpoint.\n\n'
-          + 'Most likely cause: the board process is running a pre-v2.7.5 build. '
-          + 'Restart it with:\n\n'
-          + '    kj board stop && kj board start',
-          { title: 'Board out of date' }
-        );
-        return;
-      }
-      const msg = (await res.json().catch(() => ({}))).error || `HTTP ${res.status}`;
-      await showError(msg, { title: 'Could not launch run' });
-      return;
-    }
-    const body = await res.json();
-    // Best-effort: a chokidar tick may still be in flight, so fetch
-    // once explicitly to surface the "running" state without waiting
-    // for the watcher debounce.
-    await fetch('/api/sync', { method: 'POST' }).catch(() => {});
-    await renderBoard();
-
-    // Remember the first successful planId so the section header can
-    // offer a "View log" button without the user having to re-launch.
-    const firstOk = (body.results || []).find((r) => r.ok);
-    if (firstOk && firstOk.planId) {
-      lastLaunchedPlanId = firstOk.planId;
-      lastOpenedLog = {
-        id: firstOk.planId,
-        label: 'Run log',
-        tailUrl: (offset) => `/api/plans/${encodeURIComponent(firstOk.planId)}/log?offset=${offset}`,
-      };
-      // Open the log viewer straight away — the user's mental model is
-      // "I clicked Run, I want to see what's happening", not "I clicked
-      // Run, now where do I look".
-      openLogViewer(firstOk.planId);
-    } else {
-      await showError(
-        `Pipeline launched for ${body.launched}/${body.total} plan(s) but `
-        + 'no planId came back, so there\'s no log to show.',
-        { title: 'Run started' }
-      );
-    }
-  } catch (err) {
-    await showError(err.message, { title: 'Could not launch run' });
-  }
-}

package/packages/hu-board/src/run-tracker.js

@@ -1,121 +0,0 @@
-/**
- * Run tracker — registro híbrido (memoria + disco) de procesos kj run.
- *
- * KJC-TSK-0396: el botón ⏹ Stop del board combina dos fuentes:
- *
- * 1. **Memoria** (`runs` Map) — runs lanzados desde el board vía
- *    `runPlan` en plan-mutations.js. Bajo coste, sin I/O.
- *
- * 2. **Disco** (`~/.karajan/runs/<runId>.json` vía run-registry.js) —
- *    runs lanzados desde la terminal externa (cualquier `kj run`). El
- *    CLI escribe el registro al arranque y lo borra al final. Esto da
- *    bidireccionalidad terminal ↔ board.
- *
- * `getActiveRuns(planId)` une las dos fuentes y dedupe por PID. Los
- * registros con PID muerto se filtran automáticamente y los del disco
- * se borran como cleanup (responsabilidad de run-registry).
- */
-
-import { listActiveRuns as fsList } from "karajan-core/run-registry";
-
-const runs = new Map();
-let reaperTimer = null;
-
-/**
- * Registra un run lanzado desde el board (memoria).
- *
- * @param {string} planId
- * @param {{ pid: number, huIds?: string[]|null }} info
- */
-export function trackRun(planId, info) {
-  if (!planId || !info?.pid) return;
-  const set = runs.get(planId) || new Set();
-  set.add({ pid: info.pid, huIds: info.huIds || null, startedAt: Date.now() });
-  runs.set(planId, set);
-  ensureReaper();
-}
-
-/**
- * Devuelve los runs activos para un planId. Une memoria + FS y dedupe
- * por PID. Filtra PIDs muertos.
- */
-export function getActiveRuns(planId) {
-  const seen = new Set();
-  const out = [];
-  // Memoria
-  const set = runs.get(planId);
-  if (set) {
-    for (const r of set) {
-      if (isAlive(r.pid)) {
-        seen.add(r.pid);
-        out.push({ pid: r.pid, huIds: r.huIds, startedAt: r.startedAt, source: "board" });
-      } else set.delete(r);
-    }
-    if (set.size === 0) runs.delete(planId);
-  }
-  // Disco
-  for (const entry of fsList({ planId })) {
-    if (seen.has(entry.pid)) continue;
-    seen.add(entry.pid);
-    out.push({
-      pid: entry.pid,
-      huIds: entry.huIds,
-      startedAt: entry.startedAt,
-      source: entry.source || "cli",
-      projectDir: entry.projectDir,
-    });
-  }
-  return out;
-}
-
-/**
- * Igual que getActiveRuns pero para todos los planes (memoria + FS).
- */
-export function getAllActiveRuns() {
-  const out = {};
-  // Memoria
-  for (const planId of runs.keys()) {
-    const alive = getActiveRuns(planId);
-    if (alive.length > 0) out[planId] = alive;
-  }
-  // FS — añadir planes que solo viven en disco (no se vieron arriba).
-  for (const entry of fsList()) {
-    if (!entry.planId) continue;
-    if (out[entry.planId]) continue;
-    out[entry.planId] = getActiveRuns(entry.planId);
-  }
-  return out;
-}
-
-/**
- * Quita el registro de un PID de memoria. Los registros FS los limpia
- * el propio CLI (vía registry.unregisterRun en su finally).
- */
-export function untrack(planId, pid) {
-  const set = runs.get(planId);
-  if (!set) return;
-  for (const r of set) {
-    if (r.pid === pid) set.delete(r);
-  }
-  if (set.size === 0) runs.delete(planId);
-}
-
-function isAlive(pid) {
-  if (!pid) return false;
-  try { process.kill(pid, 0); return true; }
-  catch (err) { return err.code === "EPERM"; }
-}
-
-/** Test-only reset. */
-export function _resetForTests() {
-  runs.clear();
-  if (reaperTimer) { clearInterval(reaperTimer); reaperTimer = null; }
-}
-
-function ensureReaper() {
-  if (reaperTimer || process.env.VITEST) return;
-  reaperTimer = setInterval(() => {
-    for (const planId of [...runs.keys()]) getActiveRuns(planId);
-  }, 30_000);
-  reaperTimer.unref?.();
-}

package/src/activity-log.js

@@ -1,59 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { getSessionRoot } from "./utils/paths.js";
-import { ensureDir } from "./utils/fs.js";
-
-function formatLine(entry) {
-  const ts = entry.timestamp || new Date().toISOString();
-  const lvl = (entry.level || "info").toUpperCase().padEnd(5);
-  const ctx = entry.context
-    ? Object.entries(entry.context)
-        .filter(([, v]) => v !== undefined)
-        .map(([k, v]) => `${k}=${v}`)
-        .join(" ")
-    : "";
-  const ctxStr = ctx ? ` ${ctx}` : "";
-  return `${ts} [${lvl}]${ctxStr} ${entry.message || ""}`;
-}
-
-export function createActivityLog(sessionId) {
-  const logPath = path.join(getSessionRoot(), sessionId, "activity.log");
-  let buffer = [];
-  let flushing = false;
-
-  async function flush() {
-    if (flushing || buffer.length === 0) return;
-    flushing = true;
-    const lines = buffer.splice(0);
-    try {
-      await ensureDir(path.dirname(logPath));
-      await fs.appendFile(logPath, lines.join("\n") + "\n", "utf8");
-    } catch {
-      // best-effort: I/O errors do not crash the flow
-    }
-    flushing = false;
-    if (buffer.length > 0) flush();
-  }
-
-  return {
-    write(logEntry) {
-      buffer.push(formatLine(logEntry));
-      flush();
-    },
-    writeEvent(progressEvent) {
-      const entry = {
-        timestamp: progressEvent.timestamp,
-        level: progressEvent.status === "fail" ? "error" : "info",
-        context: {
-          iteration: progressEvent.iteration,
-          stage: progressEvent.stage
-        },
-        message: progressEvent.message || progressEvent.type
-      };
-      this.write(entry);
-    },
-    get path() {
-      return logPath;
-    }
-  };
-}

package/src/agents/host-agent.js

@@ -1,38 +0,0 @@
-/**
- * Host Agent — delegates task execution to the MCP host AI via elicitation.
- *
- * Instead of spawning a subprocess, returns the prompt to the host AI
- * (Claude, Codex, etc.) for direct execution. The host has full access
- * to the codebase and tools — no subprocess overhead.
- *
- * Used when: the MCP host IS the same agent configured for a role.
- */
-
-import { BaseAgent } from "./base-agent.js";
-
-export class HostAgent extends BaseAgent {
-  constructor(config, logger, { askHost }) {
-    super("host", config, logger);
-    this._askHost = askHost;
-  }
-
-  async runTask(task) {
-    const { prompt, onOutput } = task;
-
-    if (!this._askHost) {
-      return { ok: false, output: "", error: "Host agent has no askHost callback" };
-    }
-
-    if (onOutput) onOutput({ stream: "info", line: "[host-agent] Delegating to host AI..." });
-
-    const answer = await this._askHost(prompt);
-
-    if (!answer) {
-      return { ok: false, output: "", error: "Host AI declined or returned no response" };
-    }
-
-    if (onOutput) onOutput({ stream: "info", line: "[host-agent] Host AI completed task" });
-
-    return { ok: true, output: answer, exitCode: 0 };
-  }
-}