karajan-code 4.2.1 → 4.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.2.1",
+  "version": "4.3.1",
   "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,10 +156,40 @@ 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")
-    .option("--criteria <text>", "Acceptance criteria")
+    .option("--ac <criterion>", "Acceptance criterion (repeatable; multiline strings split per line)", (v, acc) => [...acc, v], [])
+    .option("--tests <test>", "Acceptance test (repeatable; multiline strings split per line)", (v, acc) => [...acc, v], [])
+    .option("--scope <text>", "Scope of the story (files/areas)")
+    .option("--task-type <type>", "sw | infra | doc | add-tests | refactor")
+    .option("--criteria <text>", "Legacy alias for a single acceptance criterion")
     .option("--json", "Machine-readable output")
     .action(async (title, flags) => {
       await withConfig(pkgVersion, "hu", flags, async ({ config }) => {

package/src/commands/hu.js

@@ -122,15 +122,36 @@ export async function huCommand({ config = null, action, args = [], flags = {} }
         );
       }
     }
+    // KJC-TSK-0678 (issue #1296): complete HUs in ONE call. --ac / --tests
+    // are repeatable AND accept multiline strings; --criteria stays as the
+    // legacy single-criterion alias.
+    const TASK_TYPES = ["sw", "infra", "doc", "add-tests", "refactor"];
+    if (flags.taskType && !TASK_TYPES.includes(flags.taskType)) {
+      throw new Error(`invalid --task-type "${flags.taskType}" — valid: ${TASK_TYPES.join(", ")}`);
+    }
+    const splitLines = (v) => (Array.isArray(v) ? v : v ? [v] : [])
+      .flatMap((s) => String(s).split("\n")).map((s) => s.trim()).filter(Boolean);
     const hu = addHu(plan, {
       title,
       short_id: flags.id || null,
-      acceptance_criteria: flags.criteria ? [flags.criteria] : [],
+      acceptance_criteria: [...splitLines(flags.ac), ...splitLines(flags.criteria)],
+      acceptance_tests: splitLines(flags.tests),
+      scope: flags.scope || null,
+      task_type: flags.taskType || undefined,
     });
     hu.created_by = creatorLabel();
     await savePlan(projectDir, plan);
-    return emit({ id: hu.id, short_id: hu.short_id, status: hu.status, created_by: hu.created_by },
-      `✓ HU created: ${hu.short_id || hu.id} (pending, by ${hu.created_by}) — it shows up in \`kj board\``);
+    const missing = [];
+    if (hu.acceptance_criteria.length === 0) missing.push("acceptance criteria (--ac \"...\")");
+    if (hu.acceptance_tests.length === 0) missing.push("tests (--tests \"...\")");
+    if (missing.length > 0) {
+      console.warn(`⚠ incomplete spec — kj run's spec review will flag it. Missing: ${missing.join(", ")}`);
+    }
+    return emit({
+      id: hu.id, short_id: hu.short_id, status: hu.status, created_by: hu.created_by,
+      acceptance_criteria: hu.acceptance_criteria, acceptance_tests: hu.acceptance_tests,
+      scope: hu.scope, task_type: hu.task_type,
+    }, `✓ HU created: ${hu.short_id || hu.id} (pending, by ${hu.created_by}) — it shows up in \`kj board\``);
   }
 
   if (action === "move") {

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)}`;
+}

package/templates/coder-rules.md

@@ -23,6 +23,14 @@
 - Do not modify code unrelated to the task.
 - Follow existing code conventions and patterns in the repository.
 
+## Environment isolation (parallel runs)
+
+- Never hardcode ports, DB names, or docker project names — read them from env
+  vars, documenting each one in `.env.example`. When `KJ_LANE_SLOT` /
+  `KJ_PORT_OFFSET` exist in the env, derive per-task values from them so
+  parallel lanes never collide.
+- Never commit a real `.env` — only `.env.example` is versioned.
+
 ## Tests location (MANDATORY)
 
 - Tests live in a top-level `tests/` directory mirroring `src/` (e.g. a function in

package/templates/kj.config.yml

@@ -118,3 +118,11 @@ session:
   # when exceeded; resume with `kj resume`. Set to null to remove the cap.
   max_budget_usd: 5
   fail_fast_repeats: 2
+  # Per-lane setup for parallel runs (worktrees). Runs INSIDE the fresh
+  # worktree instead of the default `npm ci`. Each lane receives
+  # KJ_LANE_SLOT (0,1,2…) and KJ_PORT_OFFSET (slot-derived) in its env —
+  # derive ports, DB names and docker project names from them so lanes
+  # never collide. The coder never orchestrates git; isolation is declared
+  # here. Example:
+  #   worktree_setup: "npm ci && docker compose -p app_lane_$KJ_LANE_SLOT up -d db"
+  worktree_setup: null

package/templates/review-rules.md

@@ -4,6 +4,12 @@
 - Only raise blocking issues for concrete production risks.
 - Keep non-blocking suggestions separate.
 
+## Environment isolation
+
+- Reject changes that hardcode ports, DB names or service hostnames instead of
+  reading them from env vars, and any diff that adds a real `.env` (only
+  `.env.example` is versioned).
+
 ## File overwrite detection (BLOCKING)
 
 - If the diff shows an entire file was replaced (massive deletions + additions instead of targeted edits), flag it as BLOCKING.