karajan-code 4.2.1 → 4.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.2.1",
+  "version": "4.3.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/cli/advanced-commands.js

@@ -31,7 +31,7 @@ export const ADVANCED_GROUPS = [
   { title: "Análisis pre-run", commands: ["discover", "triage", "researcher", "architect", "onboard", "brief"] },
   { title: "Búsqueda / RAG", commands: ["rag", "qmd", "watch"] },
   { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar"] },
-  { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "undo", "standby"] },
+  { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "worktree", "undo", "standby"] },
   { title: "Infra / setup", commands: ["install-tools", "ollama", "skills", "roles", "agents", "env"] },
   { title: "Mantenimiento", commands: ["clean", "sync", "telemetry", "report-issue"] },
 ];

package/src/cli/register-meta.js

@@ -23,6 +23,7 @@ import { envInstallCommand, briefCommand } from "../commands/env.js";
 import { agentRunCommand } from "../commands/agent-run.js";
 import { reportIssueCommand } from "../commands/report-issue.js";
 import { huCommand } from "../commands/hu.js";
+import { worktreeCommand } from "../commands/worktree.js";
 import { addAdr, listAdrs } from "../environment/adr.js";
 import { formatAdvancedIndex } from "../commands/advanced.js";
 import { withConfig } from "./_shared.js";
@@ -155,6 +156,32 @@ export function registerMeta(program, { pkgVersion }) {
     });
 
   // AB-H (KJC-TSK-0658): board writes + repo ADRs for the brain.
+  // KJC-TSK-0679: isolated lanes for the host agent — ordering a command
+  // beats ordering a practice an agent can narrate without doing.
+  const wt = program.command("worktree").description("Isolated task lanes (git worktrees) for the host agent");
+  wt.command("start <slug>")
+    .description("Create a lane: worktree + feat/<slug> branch + dependency bootstrap")
+    .action(async (slug, flags) => {
+      await withConfig(pkgVersion, "worktree", flags, async ({ config }) => {
+        await worktreeCommand({ config, action: "start", args: [slug], flags });
+      });
+    });
+  wt.command("list")
+    .description("List the active lanes")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "worktree", flags, async ({ config }) => {
+        await worktreeCommand({ config, action: "list", flags });
+      });
+    });
+  wt.command("done <slug>")
+    .option("--force", "Remove the lane even with uncommitted changes")
+    .description("Remove a merged lane (refuses uncommitted changes without --force)")
+    .action(async (slug, flags) => {
+      await withConfig(pkgVersion, "worktree", flags, async ({ config }) => {
+        await worktreeCommand({ config, action: "done", args: [slug], flags });
+      });
+    });
+
   const hu = program.command("hu").description("Track work in the HU Board from any host agent (card first)");
   hu.command("add <title>")
     .option("--id <shortId>", "Human-readable short id")

package/src/commands/review-gate.js

@@ -24,7 +24,8 @@ async function rawDiff(range, extraArgs = []) {
 
 function printVerdict(record) {
   if (record.verdict === "approved") {
-    console.log(`✓ APPROVED by ${record.reviewer} (diff ${record.diffHash.slice(0, 12)})`);
+    const ws = record.workspace ? ` [${record.workspace}]` : "";
+    console.log(`✓ APPROVED by ${record.reviewer} (diff ${record.diffHash.slice(0, 12)})${ws}`);
     if (record.summary) console.log(`  ${record.summary}`);
     return;
   }

package/src/commands/worktree.js

@@ -0,0 +1,76 @@
+/**
+ * `kj worktree start|list|done` (KJC-TSK-0679) — isolated lanes for the
+ * host agent. Field case: the playbook said "one worktree per task" and an
+ * agent NARRATED the isolation while editing the project root. Ordering a
+ * command beats ordering a practice: start = worktree + feat/ branch +
+ * dependency bootstrap + the exact cd printed; done = remove after merge.
+ * Same lane dir (.kj/worktrees) and bootstrap the headless pipeline uses.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { bootstrapWorktree } from "../hu/worktree-bootstrap.js";
+
+const execFileAsync = promisify(execFile);
+const WORKTREE_DIR = ".kj/worktrees"; // shared with the headless lanes
+
+const SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export async function worktreeCommand({ config = null, action, args = [], flags = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+  const git = (gitArgs, cwd = projectDir) => execFileAsync("git", gitArgs, { cwd });
+  const lanePath = (slug) => path.join(projectDir, WORKTREE_DIR, slug);
+
+  if (action === "start") {
+    const slug = String(args[0] || "").trim();
+    if (!SLUG_RE.test(slug)) {
+      throw new Error("invalid slug — use letters, digits, dots, dashes (no slashes): kj worktree start <slug>");
+    }
+    const wtPath = lanePath(slug);
+    if (fs.existsSync(wtPath)) {
+      throw new Error(`lane "${slug}" already exists — cd ${wtPath}, or finish it with: kj worktree done ${slug}`);
+    }
+    const branch = `feat/${slug}`;
+    await git(["worktree", "add", "-b", branch, wtPath]);
+    const boot = await bootstrapWorktree({ worktreePath: wtPath, setupCommand: config?.session?.worktree_setup || null });
+    console.log(`✓ lane ready: ${branch}`);
+    console.log(`  cd ${wtPath}`);
+    console.log("  The gates travel with the repo — kj review --staged works there. When merged: kj worktree done " + slug);
+    return { path: wtPath, branch, bootstrap: boot };
+  }
+
+  if (action === "list") {
+    const laneRoot = path.join(projectDir, WORKTREE_DIR) + path.sep;
+    const { stdout } = await git(["worktree", "list", "--porcelain"]);
+    const rows = [];
+    let current = null;
+    for (const line of stdout.split("\n")) {
+      if (line.startsWith("worktree ")) current = { path: line.slice(9).trim() };
+      else if (line.startsWith("branch ") && current) {
+        current.branch = line.slice(7).trim().replace("refs/heads/", "");
+        if (current.path.startsWith(laneRoot)) {
+          rows.push({ slug: path.basename(current.path), branch: current.branch, path: current.path });
+        }
+      }
+    }
+    if (rows.length === 0) console.log("no lanes — create one with: kj worktree start <slug>");
+    for (const r of rows) console.log(`${r.slug.padEnd(24)} ${r.branch.padEnd(30)} ${r.path}`);
+    return rows;
+  }
+
+  if (action === "done") {
+    const slug = String(args[0] || "").trim();
+    const wtPath = lanePath(slug);
+    if (!fs.existsSync(wtPath)) throw new Error(`lane "${slug}" not found — see kj worktree list`);
+    const { stdout: dirty } = await git(["status", "--porcelain"], wtPath);
+    if (dirty.trim() && !flags.force) {
+      throw new Error(`lane "${slug}" has uncommitted changes — commit them (through the gate) or discard with --force`);
+    }
+    await git(["worktree", "remove", ...(flags.force ? ["--force"] : []), wtPath]);
+    console.log(`✓ lane "${slug}" removed — its branch survives; delete it after merge if you want`);
+    return { removed: true, slug };
+  }
+
+  throw new Error(`unknown action "${action}" — use: start | list | done`);
+}

package/src/environment/playbook.js

@@ -55,12 +55,15 @@ Invariants (the git gates enforce these — they are not suggestions):
 - Security findings are never overridable — not even by arbitration. You
   absorb the security role: \`kj brief security\` states what must be true.
 - Branch first: never commit on the base branch — every change reaches it
-  through an atomic PR (~150 net lines, Conventional Commits). Working on
-  more than one task, or the user needs the base tree untouched? One
-  \`git worktree\` per task — the gates travel with the repo and work there.
+  through an atomic PR (~150 net lines, Conventional Commits). More than one
+  task, or the base tree must stay untouched? \`kj worktree start <slug>\`
+  (one lane per task; \`kj worktree done <slug>\` after merge). Never CLAIM
+  isolation without proof: in a lane, \`git rev-parse --git-dir\` differs
+  from \`--git-common-dir\`.
 
 Commands: \`kj rag query\` · \`kj brief <role>\` (triage, planner, researcher,
-architect, tester, security, audit, board) · \`kj hu add|move|list\` · \`kj adr add|list\` ·
+architect, tester, security, audit, board) · \`kj hu add|move|list\` ·
+\`kj worktree start|list|done\` · \`kj adr add|list\` ·
 \`kj review --staged\` · \`kj review --check\` · \`kj solomon --position\` ·
 \`kj agent run <agent>\` · \`kj report\` · \`kj check\`
 

package/src/review/one-shot-review.js

@@ -15,6 +15,7 @@ import { resolveReviewProfile } from "./profiles.js";
 import { parseMaybeJsonString } from "./parser.js";
 import { detectAvailableAgents, detectHostAgent } from "../utils/agent-detect.js";
 import { saveVerdict } from "./verdict-store.js";
+import { detectWorkspace } from "./workspace.js";
 
 // Cross-AI preference when the configured reviewer IS the host.
 const CROSS_ORDER = ["codex", "claude", "gemini", "opencode", "aider"];
@@ -77,6 +78,8 @@ export async function runOneShotReview({
     verdict: parsed.approved ? "approved" : "rejected",
     reviewer,
     host: hostAgent || null,
+    // KJC-TSK-0680: where the review ran — makes any isolation claim auditable.
+    workspace: await detectWorkspace(projectDir),
     issues: parsed.blocking_issues || [],
     suggestions: parsed.non_blocking_suggestions || [],
     summary: parsed.summary || parsed.raw_summary || "",

package/src/review/workspace.js

@@ -0,0 +1,21 @@
+/**
+ * Workspace detection for the review gate (KJC-TSK-0680). Field case: an
+ * agent claimed worktree isolation while editing the project root. The
+ * verdict now stamps WHERE the review actually ran, using the same proof
+ * the playbook demands: in a linked worktree, `git rev-parse --git-dir`
+ * differs from `--git-common-dir`. "root" | "worktree:<name>" | null
+ * (not a git repo — the gate itself will fail later with its own error).
+ */
+import path from "node:path";
+import { runCommand } from "../utils/process.js";
+
+export async function detectWorkspace(dir) {
+  const res = await runCommand("git", ["rev-parse", "--git-dir", "--git-common-dir", "--show-toplevel"], { cwd: dir });
+  if (res.exitCode !== 0) return null;
+  const [gitDir, commonDir, toplevel] = String(res.stdout).trim().split("\n").map((l) => l.trim());
+  if (!gitDir || !commonDir) return null;
+  const resolvedGit = path.resolve(dir, gitDir);
+  const resolvedCommon = path.resolve(dir, commonDir);
+  if (resolvedGit === resolvedCommon) return "root";
+  return `worktree:${path.basename(toplevel || dir)}`;
+}