@karajan-family/code 4.21.0

package/src/config/test-harness.js

@@ -0,0 +1,78 @@
+/**
+ * Test-harness-visible config knobs — resolved once per run, then read
+ * everywhere via `config.testHarness.*`.
+ *
+ * Pre-v2.7.5 these defaults were read from `globalThis.__KJ_*` directly
+ * in production code paths — `flow-runner.js` read
+ * `globalThis.__KJ_DEFAULT_BRAIN_DECISOR`, `preflight-checks.js` read
+ * `globalThis.__KJ_DISABLE_SONAR_STAGE`, etc. The audit flagged this as
+ * spooky-action-at-a-distance: a stray test-harness leftover could flip
+ * a production default, and tests did not exercise the same path
+ * production users would.
+ *
+ * TSK-0334 isolates the globalThis lookup to a single site (this module,
+ * run during config load) and exposes the resolved knobs under
+ * `config.testHarness`. Production code reads only from `config.*`,
+ * never from `globalThis`. Tests can set either `globalThis.__KJ_*`
+ * (back-compat for the ~10 existing test files that already do) or pass
+ * `config.testHarness = { ... }` explicitly.
+ *
+ * The `tests/architecture/no-globalThis-kj.test.js` invariant fails CI
+ * if a `globalThis.__KJ_` read reappears anywhere under `src/` outside
+ * this module.
+ *
+ * Resolution order (first defined wins):
+ *   1. `config.testHarness.<key>` (explicit test or user config)
+ *   2. `globalThis.__KJ_<MACRO>`  (existing test-harness global, back-compat)
+ *   3. Documented default (second column below)
+ *
+ * | config.testHarness key         | globalThis key                  | prod default |
+ * |--------------------------------|----------------------------------|--------------|
+ * | disableSonarStage              | __KJ_DISABLE_SONAR_STAGE        | false        |
+ * | defaultSkillsMode              | __KJ_DEFAULT_SKILLS_MODE        | "auto"       |
+ * | defaultPreflightExtended       | __KJ_DEFAULT_PREFLIGHT_EXTENDED | true         |
+ * | defaultBrainDecisor            | __KJ_DEFAULT_BRAIN_DECISOR      | true         |
+ * | defaultAddyosmaniEnabled       | __KJ_DEFAULT_ADDYOSMANI_ENABLED | true         |
+ */
+
+const GLOBAL_KEYS = {
+  disableSonarStage:        "__KJ_DISABLE_SONAR_STAGE",
+  defaultSkillsMode:        "__KJ_DEFAULT_SKILLS_MODE",
+  defaultPreflightExtended: "__KJ_DEFAULT_PREFLIGHT_EXTENDED",
+  defaultBrainDecisor:      "__KJ_DEFAULT_BRAIN_DECISOR",
+  defaultAddyosmaniEnabled: "__KJ_DEFAULT_ADDYOSMANI_ENABLED",
+};
+
+const PROD_DEFAULTS = Object.freeze({
+  disableSonarStage:        false,
+  defaultSkillsMode:        "auto",
+  defaultPreflightExtended: true,
+  defaultBrainDecisor:      true,
+  defaultAddyosmaniEnabled: true,
+});
+
+/**
+ * Resolve the testHarness slice of config. Safe to call multiple times;
+ * each call re-reads globalThis so test-harness overrides applied after
+ * config load still take effect on the next resolution.
+ *
+ * @param {Partial<typeof PROD_DEFAULTS>} [explicit] - typically `config.testHarness` passed in
+ * @returns {Readonly<typeof PROD_DEFAULTS>}
+ */
+export function resolveTestHarness(explicit = {}) {
+  const out = {};
+  for (const [key, globalName] of Object.entries(GLOBAL_KEYS)) {
+    if (explicit && Object.prototype.hasOwnProperty.call(explicit, key) && explicit[key] !== undefined) {
+      out[key] = explicit[key];
+      continue;
+    }
+    const g = globalThis[globalName];
+    if (g !== undefined) {
+      out[key] = g;
+      continue;
+    }
+    out[key] = PROD_DEFAULTS[key];
+  }
+  return Object.freeze(out);
+}
+

package/src/config.js

@@ -0,0 +1,34 @@
+/**
+ * Karajan config barrel — public re-exports for back-compat.
+ *
+ * Pre-v2.7.5 this file was 636 LOC with fan-in 28: it bundled DEFAULTS
+ * data, loadConfig/writeConfig I/O, applyRunOverrides merge logic,
+ * resolveRole lookup and validateConfig schema gate — touching any of
+ * those risked rippling to a quarter of the codebase. TSK-0332 (Oleada 2
+ * of the audit refactor) split along the natural seams:
+ *
+ *   - `src/config/defaults.js`        — pure data, DEFAULTS
+ *   - `src/config/loader.js`          — fs/yaml I/O (getConfigPath,
+ *                                       loadConfig, writeConfig, etc.)
+ *   - `src/config/overrides.js`       — CLI-flag merge (applyRunOverrides)
+ *   - `src/config/role-resolver.js`   — provider/model/validate
+ *   - `src/config/schema.js`          — Valibot schema (pre-existing)
+ *
+ * This file is now a thin barrel so the 28+ consumers importing from
+ * `src/config.js` keep working unchanged. New code should import from
+ * the specific submodule.
+ *
+ * @typedef {import("./config/schema.js").KarajanConfig} KarajanConfig
+ */
+
+export { DEFAULTS } from "./config/defaults.js";
+export {
+  getConfigPath,
+  getProjectConfigPath,
+  loadProjectConfig,
+  loadConfig,
+  writeConfig,
+} from "./config/loader.js";
+export { applyRunOverrides } from "./config/overrides.js";
+export { resolveRole, validateConfig } from "./config/role-resolver.js";
+export { safeParseConfig, formatConfigIssues } from "./config/schema.js";

package/src/domains/domain-loader.js

@@ -0,0 +1,245 @@
+/**
+ * Domain Knowledge loader.
+ * Scans .karajan/domains/ (project-local) and ~/.karajan/domains/ (user-global)
+ * for DOMAIN.md files with YAML frontmatter.
+ * Project-local domains override user-global domains by directory name.
+ */
+
+import { readdir, readFile, mkdir, writeFile, stat } from "node:fs/promises";
+import { join, isAbsolute } from "node:path";
+import yaml from "js-yaml";
+import { getKarajanHome } from "../utils/paths.js";
+
+const DOMAIN_FILE = "DOMAIN.md";
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+/**
+ * Parse a DOMAIN.md file into a structured DomainFile object.
+ * @param {string} filePath — absolute path to the DOMAIN.md file
+ * @returns {Promise<DomainFile|null>} parsed domain or null on error
+ *
+ * @typedef {Object} DomainSection
+ * @property {string} heading — section heading (e.g. "Core Concepts")
+ * @property {string} content — section body (markdown)
+ *
+ * @typedef {Object} DomainFile
+ * @property {string} name
+ * @property {string} description
+ * @property {string[]} tags
+ * @property {string} version
+ * @property {string} author
+ * @property {string} visibility — "private" | "public"
+ * @property {Array<{type: string, note?: string}>} sources
+ * @property {string} content — full markdown body (after frontmatter)
+ * @property {DomainSection[]} sections — parsed markdown sections
+ * @property {string} filePath — original file path
+ * @property {string} [origin] — "project" | "user" (set by loadDomains)
+ */
+export async function parseDomainFile(filePath) {
+  let raw;
+  try {
+    raw = await readFile(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+
+  const match = raw.match(FRONTMATTER_RE);
+  if (!match) return null;
+
+  let meta;
+  try {
+    meta = yaml.load(match[1]);
+  } catch {
+    return null;
+  }
+
+  if (!meta || typeof meta !== "object" || !meta.name) return null;
+
+  const content = match[2].trim();
+  const sections = parseSections(content);
+
+  return {
+    name: meta.name,
+    description: meta.description || "",
+    tags: Array.isArray(meta.tags) ? meta.tags : [],
+    version: meta.version || "0.0.0",
+    author: meta.author || "",
+    visibility: meta.visibility || "private",
+    sources: Array.isArray(meta.sources) ? meta.sources : [],
+    content,
+    sections,
+    filePath
+  };
+}
+
+/**
+ * Split markdown content into sections by ## headings.
+ * @param {string} content
+ * @returns {DomainSection[]}
+ */
+function parseSections(content) {
+  const sections = [];
+  const lines = content.split("\n");
+  let current = null;
+
+  for (const line of lines) {
+    const headingMatch = line.match(/^##\s+(.+)/);
+    if (headingMatch) {
+      if (current) {
+        current.content = current.content.trim();
+        sections.push(current);
+      }
+      current = { heading: headingMatch[1].trim(), content: "" };
+    } else if (current) {
+      current.content += line + "\n";
+    }
+  }
+
+  if (current) {
+    current.content = current.content.trim();
+    sections.push(current);
+  }
+
+  return sections;
+}
+
+/**
+ * Auto-detect project context files (README.md, CLAUDE.md) as lightweight domains.
+ * Used as fallback when no explicit .karajan/domains/ are configured.
+ *
+ * @param {string} projectDir — absolute path to project root
+ * @returns {Promise<DomainFile[]>}
+ */
+export async function autoDetectDomains(projectDir) {
+  if (!projectDir) return [];
+
+  const candidates = ["README.md", "CLAUDE.md", "docs/README.md"];
+  const detected = [];
+
+  for (const rel of candidates) {
+    const filePath = join(projectDir, rel);
+    let content;
+    try {
+      content = await readFile(filePath, "utf-8");
+    } catch { continue; }
+
+    if (!content || content.trim().length < 20) continue;
+
+    // Truncate to first 4000 chars to avoid bloating context
+    const trimmed = content.length > 4000 ? content.slice(0, 4000) + "\n\n[...truncated]" : content;
+
+    detected.push({
+      name: `auto:${rel}`,
+      description: `Auto-detected from ${rel}`,
+      tags: [],
+      version: "0.0.0",
+      author: "",
+      visibility: "private",
+      sources: [{ type: "auto-detect", note: rel }],
+      content: trimmed,
+      sections: parseSections(trimmed),
+      filePath,
+      origin: "auto-detect"
+    });
+  }
+
+  return detected;
+}
+
+/**
+ * Load all domains from project-local and user-global directories.
+ * Falls back to auto-detecting README.md/CLAUDE.md when no explicit domains found.
+ * Project-local domains override user-global domains when directory names match.
+ *
+ * @param {string|null} projectDir — absolute path to project root (null = user-global only)
+ * @returns {Promise<DomainFile[]>}
+ */
+export async function loadDomains(projectDir) {
+  const userDir = join(getKarajanHome(), "domains");
+  const projectDomainDir = projectDir ? join(projectDir, ".karajan", "domains") : null;
+
+  // Load user-global first, then project-local overrides
+  const userDomains = await scanDomainDir(userDir, "user");
+  const projectDomains = projectDomainDir ? await scanDomainDir(projectDomainDir, "project") : [];
+
+  // Build a map keyed by directory name for merge.
+  const merged = new Map();
+
+  for (const { dirName, domain } of userDomains) {
+    merged.set(dirName, domain);
+  }
+  for (const { dirName, domain } of projectDomains) {
+    merged.set(dirName, domain); // project overrides user
+  }
+
+  const explicit = Array.from(merged.values());
+
+  // Fallback: auto-detect README.md, CLAUDE.md when no explicit domains found
+  if (explicit.length === 0 && projectDir) {
+    return autoDetectDomains(projectDir);
+  }
+
+  return explicit;
+}
+
+/**
+ * Scan a single domains directory for DOMAIN.md files.
+ * @param {string} dir — absolute path to a domains/ directory
+ * @param {string} origin — "project" | "user"
+ * @returns {Promise<Array<{dirName: string, domain: DomainFile}>>}
+ */
+async function scanDomainDir(dir, origin) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const results = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const domainPath = join(dir, entry.name, DOMAIN_FILE);
+    const domain = await parseDomainFile(domainPath);
+
+    if (domain) {
+      domain.origin = origin;
+      results.push({ dirName: entry.name, domain });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Persist an inline domain (text or file path) to .karajan/domains/inline/DOMAIN.md.
+ * If domainInput is a path to an existing .md file, reads its content.
+ * Otherwise treats it as inline text.
+ *
+ * @param {string} domainInput — inline text or absolute path to a .md file
+ * @param {string} projectDir — project root
+ */
+export async function persistInlineDomain(domainInput, projectDir) {
+  if (!domainInput || !projectDir) return;
+
+  let content = domainInput;
+
+  // If it looks like a file path, try to read it
+  if (isAbsolute(domainInput) && domainInput.endsWith(".md")) {
+    try {
+      const s = await stat(domainInput);
+      if (s.isFile()) {
+        content = await readFile(domainInput, "utf-8");
+      }
+    } catch { /* treat as inline text */ }
+  }
+
+  const domainDir = join(projectDir, ".karajan", "domains", "inline");
+  await mkdir(domainDir, { recursive: true });
+
+  const domainFile = join(domainDir, DOMAIN_FILE);
+  const wrapped = `---\nname: inline-domain\ndescription: Domain knowledge provided via --domain parameter\ntags: []\nversion: "0.0.0"\n---\n\n${content}\n`;
+  await writeFile(domainFile, wrapped, "utf-8");
+}

package/src/domains/domain-registry.js

@@ -0,0 +1,140 @@
+/**
+ * Local domain registry.
+ * Tracks installed domains in ~/.karajan/domain-registry.json.
+ * Provides search and filtering by tags/hints.
+ * Interface prepared for future remote registry extension.
+ */
+
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { getKarajanHome } from "../utils/paths.js";
+
+const REGISTRY_FILE = "domain-registry.json";
+const SCHEMA_VERSION = 1;
+
+/**
+ * @typedef {Object} RegistryEntry
+ * @property {string} name
+ * @property {string} [description]
+ * @property {string} version
+ * @property {string} source — "local" (future: "remote")
+ * @property {string} installedAt — ISO timestamp
+ * @property {string} filePath — absolute path to DOMAIN.md
+ * @property {string[]} tags
+ */
+
+export class DomainRegistry {
+  /**
+   * @param {Record<string, RegistryEntry>} domains
+   */
+  constructor(domains = {}) {
+    this._domains = domains;
+  }
+
+  /**
+   * Load registry from disk. Creates empty registry if file is missing or corrupt.
+   * @returns {Promise<DomainRegistry>}
+   */
+  static async load() {
+    const filePath = join(getKarajanHome(), REGISTRY_FILE);
+    try {
+      const raw = await readFile(filePath, "utf-8");
+      const data = JSON.parse(raw);
+      if (data?.schemaVersion === SCHEMA_VERSION && data.domains) {
+        return new DomainRegistry(data.domains);
+      }
+    } catch { /* file missing, corrupt, or wrong schema */ }
+    return new DomainRegistry();
+  }
+
+  /**
+   * Persist registry to disk.
+   */
+  async save() {
+    const home = getKarajanHome();
+    await mkdir(home, { recursive: true });
+    const filePath = join(home, REGISTRY_FILE);
+    const data = {
+      schemaVersion: SCHEMA_VERSION,
+      domains: this._domains
+    };
+    await writeFile(filePath, JSON.stringify(data, null, 2), "utf-8");
+  }
+
+  /**
+   * Register or update a domain in the registry.
+   * @param {{name: string, version?: string, tags?: string[], filePath?: string, description?: string}} domainFile
+   */
+  register(domainFile) {
+    this._domains[domainFile.name] = {
+      name: domainFile.name,
+      description: domainFile.description || "",
+      version: domainFile.version || "0.0.0",
+      source: "local",
+      installedAt: new Date().toISOString(),
+      filePath: domainFile.filePath || "",
+      tags: domainFile.tags || []
+    };
+  }
+
+  /**
+   * List domains, optionally filtered by tags and/or free-text query.
+   * @param {{tags?: string[], query?: string}} [filters]
+   * @returns {RegistryEntry[]}
+   */
+  list(filters = {}) {
+    let entries = Object.values(this._domains);
+
+    if (filters.tags?.length) {
+      const tagSet = new Set(filters.tags.map(t => t.toLowerCase()));
+      entries = entries.filter(e =>
+        e.tags?.some(t => tagSet.has(t.toLowerCase()))
+      );
+    }
+
+    if (filters.query) {
+      const q = filters.query.toLowerCase();
+      entries = entries.filter(e =>
+        (e.name || "").toLowerCase().includes(q) ||
+        (e.description || "").toLowerCase().includes(q)
+      );
+    }
+
+    return entries;
+  }
+
+  /**
+   * Search domains by triage hints.
+   * Matches hints against tags, name and description.
+   * Returns results ranked by number of matching hints.
+   * @param {string[]} hints — keywords from triage domainHints
+   * @returns {RegistryEntry[]}
+   */
+  search(hints) {
+    if (!hints?.length) return [];
+
+    const lowerHints = hints.map(h => h.toLowerCase());
+    const entries = Object.values(this._domains);
+    const scored = [];
+
+    for (const entry of entries) {
+      const searchable = [
+        entry.name || "",
+        entry.description || "",
+        ...(entry.tags || [])
+      ].join(" ").toLowerCase();
+
+      let score = 0;
+      for (const hint of lowerHints) {
+        if (searchable.includes(hint)) score++;
+      }
+
+      if (score > 0) {
+        scored.push({ entry, score });
+      }
+    }
+
+    scored.sort((a, b) => b.score - a.score);
+    return scored.map(s => s.entry);
+  }
+}

package/src/domains/domain-synthesizer.js

@@ -0,0 +1,129 @@
+/**
+ * Domain context synthesizer.
+ * Filters relevant sections from domain files based on task + hints,
+ * and compacts the output to stay within a token budget.
+ */
+
+const DEFAULT_MAX_TOKENS = 4000;
+const CHARS_PER_TOKEN = 4;
+
+/**
+ * Synthesize a domain context string from selected domains,
+ * filtered by relevance to the task and domain hints.
+ *
+ * @param {Object} params
+ * @param {string} params.task — task description
+ * @param {string[]} params.domainHints — keywords from triage
+ * @param {import('./domain-loader.js').DomainFile[]|null} params.selectedDomains
+ * @param {number} [params.maxTokens=4000] — token budget (0 = unlimited)
+ * @returns {string} synthesized markdown context or empty string
+ */
+export function synthesizeDomainContext({ task, domainHints = [], selectedDomains, maxTokens = DEFAULT_MAX_TOKENS }) {
+  if (!selectedDomains?.length) return "";
+
+  const keywords = buildKeywords(task, domainHints);
+  const domainBlocks = [];
+
+  for (const domain of selectedDomains) {
+    const sections = domain.sections || [];
+    if (!sections.length) continue;
+
+    // Score all sections but include them all (domain was explicitly selected).
+    // Sort by relevance so highest-scoring sections survive token truncation.
+    const scored = sections
+      .map(section => ({
+        section,
+        score: scoreSection(section, keywords)
+      }))
+      .sort((a, b) => b.score - a.score);
+
+    const selected = scored.map(s => s.section);
+
+    const sectionMd = selected
+      .map(s => `#### ${s.heading}\n${s.content}`)
+      .join("\n\n");
+
+    domainBlocks.push(`### ${domain.name}\n\n${sectionMd}`);
+  }
+
+  if (!domainBlocks.length) return "";
+
+  let result = domainBlocks.join("\n\n---\n\n");
+
+  // Truncate by token budget if needed
+  if (maxTokens > 0) {
+    const maxChars = maxTokens * CHARS_PER_TOKEN;
+    if (result.length > maxChars) {
+      result = truncateBySection(result, maxChars);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Build a set of lowercase keywords from task text and domain hints.
+ * @param {string} task
+ * @param {string[]} hints
+ * @returns {string[]}
+ */
+function buildKeywords(task, hints) {
+  const words = new Set();
+
+  // Add domain hints
+  for (const h of hints) {
+    words.add(h.toLowerCase());
+  }
+
+  // Extract meaningful words from task (>3 chars, skip stop words)
+  const stopWords = new Set(["the", "this", "that", "with", "from", "have", "will", "should", "could", "would", "been", "being", "their", "there", "where", "when", "what", "which", "about", "into", "some", "than", "then", "them", "they", "also", "each", "more", "most", "other"]);
+
+  const taskWords = task
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9\s-]/g, " ")
+    .split(/\s+/)
+    .filter(w => w.length > 3 && !stopWords.has(w));
+
+  for (const w of taskWords) {
+    words.add(w);
+  }
+
+  return Array.from(words);
+}
+
+/**
+ * Score a section by keyword overlap.
+ * @param {import('./domain-loader.js').DomainSection} section
+ * @param {string[]} keywords
+ * @returns {number}
+ */
+function scoreSection(section, keywords) {
+  const text = `${section.heading} ${section.content}`.toLowerCase();
+  let score = 0;
+  for (const kw of keywords) {
+    if (text.includes(kw)) score++;
+  }
+  return score;
+}
+
+/**
+ * Truncate result by dropping trailing sections to fit within maxChars.
+ * Preserves complete sections rather than cutting mid-sentence.
+ * @param {string} text
+ * @param {number} maxChars
+ * @returns {string}
+ */
+function truncateBySection(text, maxChars) {
+  // Split by section markers (#### or ###)
+  const parts = text.split(/(?=^#{3,4}\s)/m);
+  let result = "";
+
+  for (const part of parts) {
+    if (result.length + part.length > maxChars && result.length > 0) {
+      break;
+    }
+    result += part;
+  }
+
+  return result.trim();
+}

package/src/environment/adr.js

@@ -0,0 +1,45 @@
+/**
+ * ADRs in the repo (AB-H, KJC-TSK-0658) — `kj adr add|list`. Architecture
+ * decisions live as numbered markdown under .karajan/adrs/, git-tracked so
+ * the whole team (and every brain) inherits them. The architect brief's
+ * "check the ADRs before deciding" now has a target on every backend.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const ADR_DIR = path.join(".karajan", "adrs");
+
+const slugify = (t) => t.toLowerCase().replaceAll(/[^a-z0-9]+/g, "-").replaceAll(/^-|-$/g, "").slice(0, 60);
+
+export async function listAdrs(projectDir) {
+  const dir = path.join(projectDir, ADR_DIR);
+  let files;
+  try { files = await fs.readdir(dir); } catch { return []; }
+  const adrs = [];
+  for (const f of files.filter((f) => /^\d{4}-.*\.md$/.test(f)).sort()) {
+    const text = await fs.readFile(path.join(dir, f), "utf8");
+    const title = text.match(/^# (.+)$/m)?.[1] || f;
+    const status = text.match(/^Status: (.+)$/m)?.[1] || "accepted";
+    adrs.push({ file: path.join(ADR_DIR, f), number: Number(f.slice(0, 4)), title, status });
+  }
+  return adrs;
+}
+
+export async function addAdr(projectDir, { title, decision, context = "", consequences = "" }) {
+  if (!title?.trim() || !decision?.trim()) {
+    throw new Error("kj adr add requires a title and --decision");
+  }
+  const existing = await listAdrs(projectDir);
+  const number = (existing.at(-1)?.number || 0) + 1;
+  const file = path.join(ADR_DIR, `${String(number).padStart(4, "0")}-${slugify(title)}.md`);
+  const body = [
+    `# ${title}`, "",
+    `Status: accepted`, `Date: ${new Date().toISOString().slice(0, 10)}`, "",
+    ...(context ? ["## Context", "", context, ""] : []),
+    "## Decision", "", decision, "",
+    ...(consequences ? ["## Consequences", "", consequences, ""] : []),
+  ].join("\n");
+  await fs.mkdir(path.join(projectDir, ADR_DIR), { recursive: true });
+  await fs.writeFile(path.join(projectDir, file), body);
+  return { number, file, title };
+}