karajan-code 2.5.0 → 2.6.0

package/src/prompts/architect.js

@@ -9,7 +9,7 @@ const SUBAGENT_PREAMBLE = [
 
 export const VALID_VERDICTS = new Set(["ready", "needs_clarification"]);
 
-export async function buildArchitectPrompt({ task, instructions, researchContext = null, productContext = null, domainContext = null, projectDir = null, language = "en" }) {
+export async function buildArchitectPrompt({ task, instructions, researchContext = null, productContext = null, domainContext = null, projectDir = null, language = "en", provider = null }) {
   const langInstruction = getLanguageInstruction(language);
   const sections = [SUBAGENT_PREAMBLE, ...(langInstruction ? [langInstruction] : [])];
 
@@ -51,7 +51,7 @@ export async function buildArchitectPrompt({ task, instructions, researchContext
 
   if (projectDir) {
     const skills = await loadAvailableSkills(projectDir);
-    const skillSection = buildSkillSection(skills);
+    const skillSection = buildSkillSection(skills, { provider, role: "architect" });
     if (skillSection) {
       sections.push(skillSection);
     }

package/src/prompts/coder.js

@@ -33,7 +33,7 @@ const SERENA_INSTRUCTIONS = [
   "Fall back to reading files only when Serena tools are not sufficient."
 ].join("\n");
 
-export async function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, rtkAvailable = false, deferredContext = null, productContext = null, domainContext = null, plan = null, projectDir = null, language = "en" }) {
+export async function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, rtkAvailable = false, deferredContext = null, productContext = null, domainContext = null, plan = null, projectDir = null, language = "en", provider = null }) {
   const langInstruction = getLanguageInstruction(language);
   const sections = [
     serenaEnabled ? SUBAGENT_PREAMBLE_SERENA : SUBAGENT_PREAMBLE,
@@ -108,7 +108,7 @@ export async function buildCoderPrompt({ task, reviewerFeedback = null, sonarSum
 
   if (projectDir) {
     const skills = await loadAvailableSkills(projectDir);
-    const skillSection = buildSkillSection(skills);
+    const skillSection = buildSkillSection(skills, { provider });
     if (skillSection) {
       sections.push(skillSection);
     }

package/src/prompts/prompt-resolver.js

@@ -0,0 +1,127 @@
+/**
+ * Provider-aware role template resolver.
+ *
+ * Extends the legacy `resolveRoleMdPath()` contract from base-role.js to
+ * support per-provider variants without breaking existing consumers.
+ *
+ * Lookup order (first match wins):
+ *
+ *   1. <projectDir>/.karajan/roles/{role}/{provider}.md   project override, per provider
+ *   2. <projectDir>/.karajan/roles/{role}/default.md      project override, default
+ *   3. <projectDir>/.karajan/roles/{role}.md              project override, legacy flat
+ *   4. <karajanHome>/roles/{role}/{provider}.md           user home, per provider
+ *   5. <karajanHome>/roles/{role}/default.md              user home, default
+ *   6. <karajanHome>/roles/{role}.md                      user home, legacy flat
+ *   7. <built-in>/templates/roles/{role}/{provider}.md    built-in, per provider
+ *   8. <built-in>/templates/roles/{role}/default.md       built-in, default
+ *   9. <built-in>/templates/roles/{role}.md               built-in, legacy flat (back-compat)
+ *
+ * When `provider` is undefined/null the per-provider entries are skipped and
+ * only the default + legacy tiers are tried.
+ *
+ * If a provider is supplied but no per-provider file exists, we emit a
+ * one-time `prompt-resolver:fallback` event/log entry so the user knows their
+ * config asked for a variant that isn't present.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { getKarajanHome } from "../utils/paths.js";
+import { normalizeProvider } from "../utils/provider-env.js";
+
+/**
+ * Compute the full list of candidate file paths for a role template.
+ *
+ * @param {string} role                - role slug (e.g. "coder")
+ * @param {string|null|undefined} provider - provider slug or CLI name;
+ *                                           normalized internally
+ * @param {string|null|undefined} projectDir
+ * @returns {{ perProvider: string[], default: string[], legacy: string[], all: string[], provider: string|null }}
+ */
+export function resolveRolePromptPaths(role, provider, projectDir) {
+  if (!role || typeof role !== "string") {
+    throw new Error("resolveRolePromptPaths: role name is required");
+  }
+  const normalized = provider ? normalizeProvider(provider) : null;
+  const canonical = normalized && normalized.length > 0 ? normalized : null;
+
+  const homes = [];
+  if (projectDir) homes.push(path.join(projectDir, ".karajan", "roles"));
+  homes.push(path.join(getKarajanHome(), "roles"));
+
+  const builtInRoot = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "..",
+    "templates",
+    "roles"
+  );
+  homes.push(builtInRoot);
+
+  const perProvider = [];
+  const defaults = [];
+  const legacy = [];
+
+  for (const home of homes) {
+    if (canonical) {
+      perProvider.push(path.join(home, role, `${canonical}.md`));
+    }
+    defaults.push(path.join(home, role, "default.md"));
+    legacy.push(path.join(home, `${role}.md`));
+  }
+
+  // Interleave: for each home, try per-provider first, then default, then
+  // legacy. This gives the user's project override precedence over the
+  // built-in default even when they only supplied a legacy flat file.
+  const all = [];
+  for (const home of homes) {
+    if (canonical) all.push(path.join(home, role, `${canonical}.md`));
+    all.push(path.join(home, role, "default.md"));
+    all.push(path.join(home, `${role}.md`));
+  }
+
+  return { perProvider, default: defaults, legacy, all, provider: canonical };
+}
+
+/**
+ * Return the contents of the first existing candidate path. Returns null if
+ * no template is found.
+ *
+ * @param {string[]} paths
+ * @returns {Promise<{content: string, path: string}|null>}
+ */
+export async function readFirstExisting(paths) {
+  for (const p of paths) {
+    try {
+      const content = await fs.readFile(p, "utf8");
+      return { content, path: p };
+    } catch { /* file not found, keep trying */ }
+  }
+  return null;
+}
+
+/**
+ * Load role instructions resolved for a specific provider.
+ *
+ * @param {Object} args
+ * @param {string} args.role
+ * @param {string|null|undefined} args.provider
+ * @param {string|null|undefined} args.projectDir
+ * @param {{ warn?: Function, debug?: Function }} [args.logger]
+ * @returns {Promise<{ instructions: string|null, path: string|null, resolvedProvider: string|null, fellBack: boolean }>}
+ */
+export async function loadRoleInstructions({ role, provider, projectDir, logger } = {}) {
+  const { all, provider: canonical } = resolveRolePromptPaths(role, provider, projectDir);
+  const hit = await readFirstExisting(all);
+  if (!hit) {
+    return { instructions: null, path: null, resolvedProvider: canonical, fellBack: !!canonical };
+  }
+  // Detect fallback: if the user asked for a provider but we matched a path
+  // that is NOT a per-provider file, we consider it a fallback and warn.
+  const fellBack = !!canonical && !hit.path.endsWith(`${canonical}.md`);
+  if (fellBack && logger?.debug) {
+    logger.debug(`prompt-resolver: role "${role}" has no "${canonical}" variant, using ${path.basename(hit.path)}`);
+  }
+  return { instructions: hit.content, path: hit.path, resolvedProvider: canonical, fellBack };
+}

package/src/prompts/reviewer.js

@@ -24,7 +24,7 @@ const SERENA_INSTRUCTIONS = [
   "Fall back to reading files only when Serena tools are not sufficient."
 ].join("\n");
 
-export async function buildReviewerPrompt({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null, domainContext = null, projectDir = null, language = "en" }) {
+export async function buildReviewerPrompt({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null, domainContext = null, projectDir = null, language = "en", provider = null }) {
   const truncatedDiff = diff.length > 12000 ? `${diff.slice(0, 12000)}\n\n[TRUNCATED]` : diff;
 
   const langInstruction = getLanguageInstruction(language);
@@ -64,7 +64,7 @@ export async function buildReviewerPrompt({ task, diff, reviewRules, mode, seren
 
   if (projectDir) {
     const skills = await loadAvailableSkills(projectDir);
-    const skillSection = buildSkillSection(skills);
+    const skillSection = buildSkillSection(skills, { provider, role: "reviewer" });
     if (skillSection) {
       sections.push(skillSection);
     }

package/src/roles/architect-role.js

@@ -24,7 +24,9 @@ export class ArchitectRole extends AgentRole {
     const prompt = await buildArchitectPrompt({
       task, instructions: this.instructions, researchContext,
       productContext: this.config?.productContext || null,
-      domainContext: this.config?.domainContext || null
+      domainContext: this.config?.domainContext || null,
+      projectDir: this.config?.projectDir || null,
+      provider: this._resolvedProvider || (typeof this.resolveProvider === "function" ? this.resolveProvider() : null)
     });
     return { prompt };
   }

package/src/roles/base-role.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getKarajanHome } from "../utils/paths.js";
+import { loadRoleInstructions } from "../prompts/prompt-resolver.js";
 
 const ROLE_EVENTS = {
   START: "role:start",
@@ -8,6 +9,12 @@ const ROLE_EVENTS = {
   ERROR: "role:error"
 };
 
+/**
+ * Legacy flat resolver. Kept for back-compat with external callers and
+ * existing tests that assert the 3-entry candidate list. New code should use
+ * `loadRoleInstructions()` from src/prompts/prompt-resolver.js, which
+ * additionally tries per-provider and per-role subdirectories.
+ */
 function resolveRoleMdPath(roleName, projectDir) {
   const fileName = `${roleName}.md`;
   const candidates = [];
@@ -58,8 +65,22 @@ export class BaseRole {
   async init(context = {}) {
     this.context = context;
     const projectDir = this.config.projectDir || process.cwd();
-    const paths = resolveRoleMdPath(this.name, projectDir);
-    this.instructions = await loadFirstExisting(paths);
+    // Subclasses (AgentRole) can override resolveProvider to expose the
+    // provider slug for the active role, which lets the prompt resolver
+    // pick a per-provider template variant when available.
+    const provider = typeof this.resolveProvider === "function"
+      ? this.resolveProvider()
+      : null;
+    const { instructions, path: templatePath, resolvedProvider, fellBack } = await loadRoleInstructions({
+      role: this.name,
+      provider,
+      projectDir,
+      logger: this.logger,
+    });
+    this.instructions = instructions;
+    this._templatePath = templatePath;
+    this._resolvedProvider = resolvedProvider;
+    this._promptFellBack = fellBack;
     this._initialized = true;
   }
 

package/src/roles/coder-role.js

@@ -40,7 +40,9 @@ export class CoderRole extends AgentRole {
       serenaEnabled: Boolean(this.config?.serena?.enabled),
       rtkAvailable: Boolean(this.config?.rtk?.available),
       productContext: this.config?.productContext || null,
-      domainContext: this.config?.domainContext || null
+      domainContext: this.config?.domainContext || null,
+      projectDir: this.config?.projectDir || null,
+      provider: this._resolvedProvider || (typeof this.resolveProvider === "function" ? this.resolveProvider() : null)
     });
     return { prompt };
   }

package/src/roles/security-role.js

@@ -1,5 +1,6 @@
 import { AgentRole } from "./agent-role.js";
 import { extractFirstJson } from "../utils/json-extract.js";
+import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -23,6 +24,17 @@ export class SecurityRole extends AgentRole {
       `## Task\n${task}`
     );
     if (diff) sections.push(`## Git diff to audit\n${diff}`);
+
+    // Inject security-relevant skills (owasp-*, security-*, sast-*) filtered
+    // by role=security.
+    const projectDir = this.config?.projectDir || process.cwd();
+    const skills = await loadAvailableSkills(projectDir);
+    const skillSection = buildSkillSection(skills, {
+      provider: this._resolvedProvider || (typeof this.resolveProvider === "function" ? this.resolveProvider() : null),
+      role: "security",
+    });
+    if (skillSection) sections.push(skillSection);
+
     return { prompt: sections.join("\n\n") };
   }
 

package/src/roles/tester-role.js

@@ -1,6 +1,7 @@
 import { AgentRole } from "./agent-role.js";
 import { extractFirstJson } from "../utils/json-extract.js";
 import { detectTestFramework } from "../utils/project-detect.js";
+import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -108,6 +109,16 @@ export class TesterRole extends AgentRole {
     );
     if (diff) sections.push(`## Git diff\n${diff}`);
     if (sonarIssues) sections.push(`## Sonar test issues\n${sonarIssues}`);
+
+    // Inject test-relevant skills (filtered by role=tester to only include
+    // testing patterns like pytest-patterns, vitest-patterns, etc.)
+    const skills = await loadAvailableSkills(projectDir);
+    const skillSection = buildSkillSection(skills, {
+      provider: this._resolvedProvider || (typeof this.resolveProvider === "function" ? this.resolveProvider() : null),
+      role: "tester",
+    });
+    if (skillSection) sections.push(skillSection);
+
     return { prompt: sections.join("\n\n") };
   }
 

package/src/session/journal/decisions-writer.js

@@ -0,0 +1,200 @@
+/**
+ * Build a human-readable `decisions.md` journal file summarizing every
+ * Solomon ruling and Brain decision made during a session.
+ *
+ * Acceptance criterion (KJC-TSK-0287):
+ *   - Given Solomon was invoked at least once → decisions.md is written with
+ *     timestamp, trigger, conflict context, ruling (action + reasoning),
+ *     and resulting actions for every invocation.
+ *   - Given Solomon was NOT invoked → decisions.md is NOT created.
+ *
+ * Brain routing decisions (from KJC-TSK-0322) are appended as a secondary
+ * section when present, since they share the same "decisions" semantics.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getSessionRoot } from "../../utils/paths.js";
+
+/**
+ * @typedef {Object} SolomonRuling
+ * @property {string} at                         - ISO timestamp
+ * @property {string} stage                      - conflict stage (reviewer, brain-routing, ...)
+ * @property {string} trigger                    - short reason the invocation was triggered
+ * @property {Object} conflict                   - conflict context (task, reason, summary)
+ * @property {string} ruling                     - approve / continue / escalate_human / create_subtask / ...
+ * @property {string} [reasoning]
+ * @property {string[]} [conditions]
+ * @property {string} [alternativeAgent]
+ * @property {string} [result]                   - what the orchestrator did with the ruling
+ */
+
+/**
+ * @typedef {Object} BrainDecisionRecord
+ * @property {number} seq
+ * @property {string} at
+ * @property {string} intent
+ * @property {string[]} rolesOn
+ * @property {string} confidence
+ * @property {string} rationale
+ * @property {string[]} appliedOverrides
+ */
+
+function esc(text) {
+  return String(text ?? "").replace(/\|/g, "\\|");
+}
+
+function formatConditions(conditions) {
+  if (!Array.isArray(conditions) || conditions.length === 0) return "—";
+  return conditions.map((c) => `- ${esc(c)}`).join("\n");
+}
+
+function formatConflict(conflict) {
+  if (!conflict) return "—";
+  const parts = [];
+  if (conflict.task) parts.push(`**Task**: ${esc(conflict.task.slice(0, 200))}${conflict.task.length > 200 ? "…" : ""}`);
+  if (conflict.reason) parts.push(`**Reason**: ${esc(conflict.reason)}`);
+  if (conflict.summary) parts.push(`**Summary**: ${esc(conflict.summary)}`);
+  return parts.length > 0 ? parts.join("\n") : "—";
+}
+
+/**
+ * Render a Solomon ruling as a Markdown subsection.
+ * @param {SolomonRuling} ruling
+ * @param {number} index
+ * @returns {string}
+ */
+function renderRuling(ruling, index) {
+  const at = ruling.at || "(unknown timestamp)";
+  const header = `### ${index + 1}. Solomon @ ${at} — ${esc(ruling.ruling || "unknown")}`;
+  const lines = [
+    header,
+    "",
+    `- **Stage**: ${esc(ruling.stage || "?")}`,
+    `- **Trigger**: ${esc(ruling.trigger || "?")}`,
+    `- **Ruling**: \`${esc(ruling.ruling || "?")}\``,
+  ];
+  if (ruling.alternativeAgent) lines.push(`- **Alternative agent**: ${esc(ruling.alternativeAgent)}`);
+  if (ruling.result) lines.push(`- **Applied result**: ${esc(ruling.result)}`);
+  lines.push("");
+  if (ruling.reasoning) {
+    lines.push("**Reasoning:**", "");
+    lines.push(ruling.reasoning.trim(), "");
+  }
+  if (ruling.conditions?.length) {
+    lines.push("**Conditions:**", "");
+    lines.push(formatConditions(ruling.conditions), "");
+  }
+  lines.push("**Conflict context:**", "");
+  lines.push(formatConflict(ruling.conflict), "");
+  return lines.join("\n");
+}
+
+function renderBrainDecision(decision, index) {
+  return [
+    `### ${index + 1}. Brain @ ${decision.at} — ${esc(decision.intent)}`,
+    "",
+    `- **Confidence**: ${esc(decision.confidence)}`,
+    `- **Roles on**: ${(decision.rolesOn || []).map(esc).join(", ") || "—"}`,
+    `- **Overrides applied**: ${(decision.appliedOverrides || []).map(esc).join(", ") || "—"}`,
+    "",
+    `> ${esc(decision.rationale || "")}`,
+    "",
+  ].join("\n");
+}
+
+/**
+ * Build the Markdown content for a session. Returns `null` if no Solomon
+ * rulings are present (per acceptance criteria — no Solomon, no file).
+ *
+ * @param {Object} session
+ * @returns {string|null}
+ */
+export function buildDecisionsMarkdown(session) {
+  const rulings = Array.isArray(session?.solomonRulings) ? session.solomonRulings : [];
+  const brainDecisions = Array.isArray(session?.brainDecisions) ? session.brainDecisions : [];
+
+  // AC: no Solomon invocation → do not generate the file.
+  if (rulings.length === 0) return null;
+
+  const sessionId = session?.id || "(unknown)";
+  const header = [
+    `# Session decisions — ${sessionId}`,
+    "",
+    `_Generated at ${new Date().toISOString()}._`,
+    "",
+    `This journal records every decision the pipeline delegated to Solomon, plus Brain routing decisions for cross-reference.`,
+    "",
+    "## Summary",
+    "",
+    `- Solomon invocations: **${rulings.length}**`,
+    `- Brain routing decisions: **${brainDecisions.length}**`,
+    "",
+    "---",
+    "",
+    "## Solomon rulings",
+    "",
+  ].join("\n");
+
+  const solomonSection = rulings.map((r, i) => renderRuling(r, i)).join("\n---\n\n");
+
+  const brainSection = brainDecisions.length > 0
+    ? "\n---\n\n## Brain routing decisions\n\n" + brainDecisions.map((d, i) => renderBrainDecision(d, i)).join("\n")
+    : "";
+
+  return header + solomonSection + brainSection + "\n";
+}
+
+/**
+ * Persist decisions.md to the session's journal directory. No-op when there
+ * are no Solomon rulings (per acceptance criteria).
+ *
+ * Path resolution (first match wins):
+ *   1. options.journalDir       — direct path to the session journal directory
+ *   2. options.sessionRoot + id — combines with session.id
+ *   3. getSessionRoot() + id    — default Karajan session root
+ *
+ * @param {Object} session
+ * @param {{ journalDir?: string, sessionRoot?: string, logger?: Object }} [options]
+ * @returns {Promise<{ written: boolean, path: string|null }>}
+ */
+export async function writeDecisionsJournal(session, options = {}) {
+  const content = buildDecisionsMarkdown(session);
+  if (content === null) return { written: false, path: null };
+
+  const sessionDir = options.journalDir
+    || path.join(options.sessionRoot || getSessionRoot(), session.id);
+  const filePath = path.join(sessionDir, "decisions.md");
+  try {
+    await fs.mkdir(sessionDir, { recursive: true });
+    await fs.writeFile(filePath, content, "utf8");
+    options.logger?.info?.(`Wrote decisions journal: ${filePath}`);
+    return { written: true, path: filePath };
+  } catch (err) {
+    options.logger?.warn?.(`Failed to write decisions journal (non-blocking): ${err.message}`);
+    return { written: false, path: null };
+  }
+}
+
+/**
+ * Append a Solomon ruling to session.solomonRulings. Creates the array if
+ * absent. Callers (invokeSolomon) pass the structured record.
+ *
+ * @param {Object} session
+ * @param {SolomonRuling} record
+ */
+export function recordSolomonRuling(session, record) {
+  if (!session) return;
+  if (!Array.isArray(session.solomonRulings)) session.solomonRulings = [];
+  session.solomonRulings.push({
+    at: record.at || new Date().toISOString(),
+    stage: record.stage || "unknown",
+    trigger: record.trigger || "",
+    conflict: record.conflict || {},
+    ruling: record.ruling || "unknown",
+    reasoning: record.reasoning || "",
+    conditions: Array.isArray(record.conditions) ? [...record.conditions] : [],
+    alternativeAgent: record.alternativeAgent || null,
+    result: record.result || "",
+  });
+}