@karajan-family/code 4.21.0

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/config/defaults.js

@@ -0,0 +1,270 @@
+/**
+ * Karajan's default configuration — the baseline every user's config is
+ * merged on top of.
+ *
+ * This is **pure data**. It was extracted from `src/config.js` in TSK-0332
+ * (Oleada 2 of the v2.7.4 audit refactor) so that consumers that only
+ * need the shape (schema tests, display, docs) don't drag the loader's
+ * fs/yaml imports.
+ *
+ * Source of truth is here; `src/config.js` re-exports `DEFAULTS` for
+ * back-compat.
+ */
+
+const DEFAULTS = {
+  coder: "claude",
+  reviewer: "codex",
+  roles: {
+    planner: { provider: null, model: null },
+    coder: { provider: null, model: null },
+    reviewer: { provider: null, model: null },
+    refactorer: { provider: null, model: null },
+    solomon: { provider: null, model: null },
+    researcher: { provider: null, model: null },
+    tester: { provider: null, model: null },
+    security: { provider: null, model: null },
+    impeccable: { provider: null, model: null },
+    triage: { provider: null, model: null },
+    discover: { provider: null, model: null },
+    architect: { provider: null, model: null },
+    hu_reviewer: { provider: null, model: null },
+    start: { provider: null, model: "haiku" }
+  },
+  pipeline: {
+    planner: { enabled: false },
+    refactorer: { enabled: false },
+    solomon: { enabled: true },
+    researcher: { enabled: false },
+    tester: { enabled: true },
+    security: { enabled: true },
+    impeccable: { enabled: false },
+    perf: { enabled: false },
+    triage: { enabled: true },
+    discover: { enabled: false },
+    architect: { enabled: false },
+    hu_reviewer: { enabled: false },
+    brain: { enabled: true },
+    auto_simplify: true
+  },
+  brain: {
+    enabled: true,
+    provider: "claude",
+    bypass_solomon_on_correctness: true,
+    max_consecutive_verification_failures: 2
+  },
+  review_mode: "standard",
+  max_iterations: 5,
+  hu_max_iterations: 3,
+  // Hard per-run spend ceiling, ON by default (KJC-TSK-0621): a stuck or
+  // runaway run must never drain a subscription quota unattended. Explicit
+  // null in the user's config opts out (no cap).
+  max_budget_usd: 5,
+  // ENV-D1 (KJC-TSK-0642): where work items live. The HU Board ships with
+  // kj; "planning-game" routes the v4 playbook to the user's PG MCP;
+  // "external" (KJC-TSK-0684) points card-first at the project's own board
+  // (Linear, Trello, Jira, GitHub Issues…) named in board.name — worked
+  // through the host agent's MCP/tools, never mirrored by kj. There is NO
+  // "none": Karajan does not run without a board.
+  state_backend: "hu-board",
+  // verify_cmd (KJC-TSK-0732): user adapter that checks a card ref against
+  // the real tracker — prints {exists, live, status} JSON; {ref} substituted.
+  board: { name: null, verify_cmd: null },
+  // Method gates (KJC-PCS-0068): rules climb from playbook text to
+  // deterministic enforcement. card_first: "auto" = block with hu-board
+  // (fully verifiable), warn with planning-game/external (presence only);
+  // explicit "warn" | "block" override. Release branches are exempt.
+  method_gates: {
+    card_first: "auto",
+    card_first_exempt_branches: ["chore/release-"],
+    // MG-B: source changes without a test change — "warn" | "block".
+    tests_with_code: "warn",
+    // MG-C: informative nudge when the staged diff exceeds this many
+    // added lines (0 disables). The project's CI owns any hard budget.
+    pr_size_warn: 150
+  },
+  review_rules: "./.karajan/review-rules.md",
+  coder_rules: "./.karajan/coder-rules.md",
+  base_branch: "main",
+  coder_options: { model: null, auto_approve: true, fallback_coder: null },
+  reviewer_options: {
+    output_format: "json",
+    require_schema: true,
+    model: null,
+    deterministic: true,
+    retries: 1,
+    fallback_reviewer: null
+  },
+  development: {
+    methodology: "tdd",
+    require_test_changes: true,
+    // KJC-TSK-0398: opt-in red-then-green gate. When true, the pipeline
+    // stashes source files and re-runs the test suite to confirm the new
+    // tests actually fail without the implementation. Off by default to
+    // preserve current iteration latency.
+    require_red_then_green: false,
+    test_file_patterns: ["/tests/", "/__tests__/", ".test.", ".spec."],
+    source_file_extensions: [".js", ".jsx", ".ts", ".tsx", ".py", ".go", ".java", ".rb", ".php", ".cs"]
+  },
+  sonarqube: {
+    enabled: true,
+    host: "http://localhost:9000",
+    external: false,
+    container_name: "karajan-sonarqube",
+    network: "karajan_sonar_net",
+    volumes: {
+      data: "karajan_sonar_data",
+      logs: "karajan_sonar_logs",
+      extensions: "karajan_sonar_extensions"
+    },
+    timeouts: {
+      healthcheck_seconds: 5,
+      compose_up_ms: 300000,
+      compose_control_ms: 120000,
+      logs_ms: 30000,
+      scanner_ms: 900000
+    },
+    token: null,
+    project_key: null,
+    admin_user: null,
+    admin_password: null,
+    coverage: {
+      enabled: false,
+      command: null,
+      timeout_ms: 300000,
+      block_on_failure: true,
+      lcov_report_path: null
+    },
+    quality_gate: true,
+    enforcement_profile: "pragmatic",
+    gate_block_on: [
+      "new_reliability_rating=E",
+      "new_security_rating=E",
+      "new_maintainability_rating=E",
+      "new_coverage<80",
+      "new_duplicated_lines_density>5"
+    ],
+    fail_on: ["BLOCKER", "CRITICAL"],
+    ignore_on: ["INFO"],
+    max_scan_retries: 3,
+    scanner: {
+      sources: "src,public,lib",
+      exclusions: "**/node_modules/**,**/fake-apps/**,**/scripts/**,**/playground/**,**/dist/**,**/build/**,**/*.min.js",
+      test_inclusions: "**/*.test.js,**/*.spec.js,**/tests/**,**/__tests__/**",
+      coverage_exclusions: "**/tests/**,**/__tests__/**,**/*.test.js,**/*.spec.js",
+      disabled_rules: ["javascript:S1116", "javascript:S3776"]
+    }
+  },
+  sonarcloud: {
+    enabled: false,
+    organization: null,
+    token: null,
+    project_key: null,
+    host: "https://sonarcloud.io",
+    scanner: {
+      sources: "src,public,lib",
+      exclusions: "**/node_modules/**,**/dist/**,**/build/**,**/*.min.js",
+      test_inclusions: "**/*.test.js,**/*.spec.js,**/tests/**,**/__tests__/**"
+    }
+  },
+  hu_board: {
+    enabled: false,
+    port: 4000,
+    auto_start: false
+  },
+  language: "en",
+  hu_language: "en",
+  policies: {},
+  serena: { enabled: false },
+  planning_game: { enabled: false, project_id: null, codeveloper: null },
+  skills: {
+    mode: "auto",
+    sources: ["addyosmani", "openskills", "local"],
+    addyosmani: {
+      enabled: true,
+      refreshDays: 7,
+      repoUrl: "https://github.com/addyosmani/agent-skills.git"
+    }
+  },
+  ci: { enabled: false, review_event: "kj-review", comment_event: "kj-comment", comment_prefix: true },
+  git: { auto_commit: false, auto_push: false, auto_pr: false, auto_rebase: true, branch_prefix: "feat/" },
+  output: { report_dir: "./.reviews", log_level: "info", quiet: true },
+  budget: {
+    warn_threshold_pct: 80,
+    currency: "usd",
+    exchange_rate_eur: 0.92
+  },
+  model_selection: {
+    enabled: true,
+    tiers: {},
+    role_overrides: {}
+  },
+  session: {
+    // Opt-in per-iteration supervision (KJC-TSK-0628): pause after each
+    // iteration with a report and ask continue / stop / instructions.
+    iteration_gate: false,
+    // Concurrent HU lanes per plan run (KJC-TSK-0626). 1 = sequential.
+    // Raising it multiplies token burn rate — the plan budget scales with it.
+    max_parallel_hus: 1,
+    // Command run inside each fresh lane worktree before the coder starts
+    // (KJC-TSK-0630). null = auto-detect: `npm ci` when package-lock.json
+    // exists, nothing otherwise. Submodules are always initialized first.
+    worktree_setup: null,
+    max_iteration_minutes: 30,
+    max_total_minutes: 120,
+    max_planner_minutes: 60,
+    checkpoint_interval_minutes: 5,
+    max_agent_silence_minutes: 20,
+    fail_fast_repeats: 2,
+    repeat_detection_threshold: 2,
+    max_sonar_retries: 3,
+    max_reviewer_retries: 3,
+    max_tester_retries: 1,
+    max_security_retries: 1,
+    max_auto_resumes: 2,
+    expiry_days: 30
+  },
+  failFast: {
+    repeatThreshold: 2
+  },
+  webperf: {
+    enabled: true,
+    devtools_mcp: false,
+    thresholds: { lcp: 2500, cls: 0.1, inp: 200 }
+  },
+  rag: {
+    // KJC-TSK-0455 — Auto-refresh the local RAG index. `onRun` runs a
+    // delta re-index before every `kj run`; `onCommit` is consulted by
+    // `kj rag install-hooks` to decide whether to install the post-merge
+    // hook. Both default ON; flip to false to opt out without uninstalling.
+    autoUpdate: { onCommit: true, onRun: true },
+    // KJC-TSK-0682 — sensitivity of the indexed code. Cloud embedders
+    // (openai/voyage/cohere/mistral) require an explicit "public"; the
+    // safe default blocks them (local ollama/onnx always allowed).
+    sensitivity: "internal"
+  },
+  // Opt-in. Set by the `kj init` wizard (explicit consent prompt in the OS
+  // locale). When the key is absent or false, no events are sent. See
+  // src/utils/telemetry.js and the Privacy & Telemetry section of README.md.
+  telemetry: false,
+  guards: {
+    output: {
+      enabled: true,
+      patterns: [],
+      protected_files: [],
+      on_violation: "block"
+    },
+    perf: {
+      enabled: true,
+      patterns: [],
+      block_on_warning: false,
+      frontend_extensions: []
+    },
+    intent: {
+      enabled: false,
+      patterns: [],
+      confidence_threshold: 0.85
+    }
+  }
+};
+export { DEFAULTS };
+

package/src/config/loader.js

@@ -0,0 +1,204 @@
+/**
+ * Config I/O layer — reads and writes Karajan's YAML config files.
+ *
+ * Extracted from `src/config.js` in TSK-0332 (Oleada 2 of the v2.7.4 audit
+ * refactor). The public API (`loadConfig`, `writeConfig`, `getConfigPath`,
+ * `getProjectConfigPath`, `loadProjectConfig`) stayed exactly the same so
+ * the 28+ files that imported from `src/config.js` didn't have to change.
+ *
+ * Responsibilities:
+ *   - Resolve the global config path under `~/.karajan/kj.config.yml`
+ *     (respecting `KJ_HOME`).
+ *   - Resolve the project config path under `<projectDir>/.karajan/kj.config.yml`.
+ *   - Load + merge global over DEFAULTS, then project over merged.
+ *   - Validate the merged config via the Valibot schema.
+ *   - Record deprecation flags (e.g. `sonarqube.enabled` → ignored since v2.7.4)
+ *     for the orchestrator to surface as warnings at run start.
+ *
+ * Intentionally NOT here: flag overrides (src/config/overrides.js),
+ * role resolution (src/config/role-resolver.js), DEFAULTS (src/config/defaults.js).
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+import { ensureDir, exists } from "../utils/fs.js";
+import { getKarajanHome } from "../utils/paths.js";
+import { safeParseConfig, formatConfigIssues } from "./schema.js";
+import { DEFAULTS } from "./defaults.js";
+import { resolveTestHarness } from "./test-harness.js";
+
+/**
+ * Parse a YAML config file with an actionable error message.
+ * Plain `yaml.load` throws `YAMLException: bad indentation ...` with NO
+ * file path, so a single bad edit bricked the entire CLI (including
+ * `kj doctor`, the one command meant to diagnose it). Wrapping every
+ * read site in the same prefix means the user always knows which file
+ * they need to fix.
+ * @param {string} raw - file contents
+ * @param {string} filePath - absolute path (for the error message)
+ * @returns {object}
+ */
+function parseYamlOrThrow(raw, filePath) {
+  try {
+    return yaml.load(raw, { json: true }) || {};
+  } catch (err) {
+    const detail = err?.message || String(err);
+    const e = new Error(`Invalid YAML in ${filePath}:\n  ${detail}`);
+    e.cause = err;
+    e.code = "INVALID_YAML";
+    e.path = filePath;
+    throw e;
+  }
+}
+
+export function mergeDeep(base, override) {
+  const output = { ...base };
+  for (const [key, value] of Object.entries(override || {})) {
+    if (Array.isArray(value)) {
+      output[key] = value;
+    } else if (value && typeof value === "object") {
+      output[key] = mergeDeep(base[key] || {}, value);
+    } else {
+      output[key] = value;
+    }
+  }
+  return output;
+}
+
+export function getConfigPath() {
+  return path.join(getKarajanHome(), "kj.config.yml");
+}
+
+export function getProjectConfigPath(projectDir = process.cwd()) {
+  return path.join(projectDir, ".karajan", "kj.config.yml");
+}
+
+export async function loadProjectConfig(projectDir = process.cwd()) {
+  const projectConfigPath = getProjectConfigPath(projectDir);
+  if (!(await exists(projectConfigPath))) {
+    return null;
+  }
+  const raw = await fs.readFile(projectConfigPath, "utf8");
+  return parseYamlOrThrow(raw, projectConfigPath);
+}
+
+async function loadProjectPricingOverrides(projectDir = process.cwd()) {
+  const projectConfigPath = path.join(projectDir, ".karajan.yml");
+  if (!(await exists(projectConfigPath))) {
+    return null;
+  }
+
+  const raw = await fs.readFile(projectConfigPath, "utf8");
+  const parsed = parseYamlOrThrow(raw, projectConfigPath);
+  const pricing = parsed?.budget?.pricing;
+  if (!pricing || typeof pricing !== "object") {
+    return null;
+  }
+
+  return pricing;
+}
+
+export async function loadConfig(projectDir) {
+  const configPath = getConfigPath();
+  const projectPricing = await loadProjectPricingOverrides(projectDir);
+
+  // Load global config
+  let globalConfig = {};
+  const globalExists = await exists(configPath);
+  if (globalExists) {
+    const raw = await fs.readFile(configPath, "utf8");
+    globalConfig = parseYamlOrThrow(raw, configPath);
+  }
+
+  // Load project config (.karajan/kj.config.yml)
+  const projectConfig = await loadProjectConfig(projectDir);
+
+  // KJC-TSK-0395: enforce the local-overrides-global hierarchy. A project
+  // config with no global counterpart is almost always user error (copied
+  // a .karajan dir from another repo, edited the wrong file, etc.) and
+  // would silently behave like a global config without the defaults
+  // people expect. Refuse with an actionable message.
+  if (projectConfig && !globalExists) {
+    throw new Error(
+      `Local config found at ${getProjectConfigPath(projectDir)} but no global config exists.\n` +
+      "Local configs are merged ON TOP of the global one — run `kj init --global` first to create the base."
+    );
+  }
+
+  // Merge: DEFAULTS < global < project
+  let merged = mergeDeep(DEFAULTS, globalConfig);
+  if (projectConfig) {
+    merged = mergeDeep(merged, projectConfig);
+  }
+
+  if (projectPricing) {
+    merged.budget = mergeDeep(merged.budget || {}, { pricing: projectPricing });
+  }
+
+  // KJC-TSK-0318 — schema-validate the merged config so invalid values
+  // (review_mode typos, max_iterations=0, out-of-range ports) surface at
+  // load time with a clear error instead of crashing deep inside the
+  // orchestrator. safeParse + explicit error prefix keeps the message
+  // actionable.
+  const validation = safeParseConfig(merged);
+  if (!validation.success) {
+    throw new Error(`Invalid Karajan config:\n${formatConfigIssues(validation.issues)}`);
+  }
+
+  // Deprecation tracking — `sonarqube.enabled` was a footgun: users would
+  // set it to `false` in their global ~/.karajan/kj.config.yml and then
+  // wonder why Sonar didn't run on a code task. Since v2.7.4 Sonar is
+  // intrinsic to Karajan for code tasks; the field is ignored. We surface
+  // a warning at run start (see emitConfigDeprecations in flow-runner.js)
+  // so users notice and clean up their config. Don't throw — keep
+  // back-compat so existing scripts keep working.
+  const userSetSonarEnabled = (globalConfig?.sonarqube?.enabled !== undefined)
+    || (projectConfig?.sonarqube?.enabled !== undefined);
+  if (userSetSonarEnabled) {
+    merged._deprecated = merged._deprecated || {};
+    merged._deprecated.sonarqubeEnabledKey = true;
+  }
+
+  merged.testHarness = resolveTestHarness(merged.testHarness);
+  return { config: merged, path: configPath, exists: globalExists, hasProjectConfig: !!projectConfig };
+}
+
+/**
+ * Runtime-only keys that the loader synthesises on every load (or that
+ * a wizard uses as transient in-memory hints). They MUST NOT survive
+ * to the on-disk YAML — otherwise the `kj run` deprecation warning
+ * fossilises (KJC-BUG-0036, observed in dogfooding 2026-05-07: the
+ * `_deprecated.sonarqubeEnabledKey: true` block ended up baked into
+ * `~/.karajan/kj.config.yml` and re-fired the warning on every run
+ * even after the user cleaned `sonarqube.enabled`).
+ *
+ * Pure: returns a shallow-copied config without the runtime keys —
+ * the caller's object is left untouched.
+ */
+function stripRuntimeOnlyKeys(config) {
+  if (!config || typeof config !== "object") return config;
+  const out = { ...config };
+  // _deprecated is loader-synthesised — never written intentionally.
+  if ("_deprecated" in out) delete out._deprecated;
+  // sonarqube.enabled was deprecated in v2.7.4. The init wizard still
+  // uses it as a hint to drive setupSonarQube during install, but the
+  // runtime ignores it. Persisting it would re-trigger the deprecation
+  // warning on every subsequent kj run.
+  if (out.sonarqube && typeof out.sonarqube === "object"
+      && Object.prototype.hasOwnProperty.call(out.sonarqube, "enabled")) {
+    const rest = { ...out.sonarqube };
+    delete rest.enabled;
+    out.sonarqube = rest;
+  }
+  return out;
+}
+
+export async function writeConfig(configPath, config) {
+  await ensureDir(path.dirname(configPath));
+  const sanitized = stripRuntimeOnlyKeys(config);
+  await fs.writeFile(configPath, yaml.dump(sanitized, { lineWidth: 120 }), "utf8");
+}
+
+// Declarative mappings for applyRunOverrides to reduce cognitive complexity.
+