karajan-code 2.4.1 → 2.6.0

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

package/src/session/journal/iteration-logger.js

@@ -0,0 +1,194 @@
+/**
+ * Per-iteration journal entries for `.reviews/{sessionId}/iterations.md`.
+ *
+ * The orchestrator calls `recordIteration(session, data)` after every
+ * iteration of the coder/reviewer loop completes. Entries are appended to
+ * `session._journalIterations` and rendered as Markdown at session end.
+ *
+ * Acceptance criterion (KJC-TSK-0287):
+ *   - Given a kj run with multiple iterations → iterations.md exists with
+ *     one section per iteration containing: number, coder summary, reviewer
+ *     blocking issues, sonar issues (if any), Solomon ruling (if any),
+ *     duration.
+ */
+
+/**
+ * @typedef {Object} IterationData
+ * @property {number} iteration                                  - 1-based index
+ * @property {number} durationMs
+ * @property {string} [coderSummary]
+ * @property {string} [reviewerSummary]
+ * @property {Array<{id?:string, severity?:string, file?:string, line?:number, description?:string}>} [blockingIssues]
+ * @property {string} [sonarSummary]
+ * @property {number} [sonarIssuesFound]
+ * @property {number} [sonarIssuesResolved]
+ * @property {string} [testerSummary]
+ * @property {string} [securitySummary]
+ * @property {{ ruling?:string, reasoning?:string }} [solomon]   - only present when Solomon ran in this iteration
+ */
+
+function esc(text) {
+  return String(text ?? "").replace(/\|/g, "\\|");
+}
+
+function formatDuration(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return "—";
+  if (ms < 1000) return `${ms}ms`;
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  const rs = s % 60;
+  return `${m}m ${rs}s`;
+}
+
+function formatBlockingIssues(issues) {
+  if (!Array.isArray(issues) || issues.length === 0) return null;
+  const lines = ["**Blocking issues**:"];
+  for (const issue of issues) {
+    const sev = issue.severity ? `[${issue.severity}] ` : "";
+    const loc = issue.file ? ` — \`${esc(issue.file)}${issue.line ? `:${issue.line}` : ""}\`` : "";
+    const id = issue.id ? `${issue.id}: ` : "";
+    const desc = esc(issue.description || issue.message || "(no description)");
+    lines.push(`- ${sev}${id}${desc}${loc}`);
+  }
+  return lines.join("\n");
+}
+
+function formatSonarBlock(data) {
+  const parts = [];
+  if (data.sonarSummary) parts.push(esc(data.sonarSummary));
+  if (Number.isFinite(data.sonarIssuesFound)) {
+    const resolved = Number.isFinite(data.sonarIssuesResolved) ? ` (${data.sonarIssuesResolved} resolved)` : "";
+    parts.push(`Issues: ${data.sonarIssuesFound}${resolved}`);
+  }
+  return parts.length > 0 ? parts.join(" · ") : null;
+}
+
+function formatSolomonBlock(solomon) {
+  if (!solomon || !solomon.ruling) return null;
+  const lines = [`**Ruling**: \`${esc(solomon.ruling)}\``];
+  if (solomon.reasoning) lines.push(`**Reasoning**: ${esc(solomon.reasoning)}`);
+  return lines.join("  \n");
+}
+
+/**
+ * Render a single iteration as a Markdown section.
+ *
+ * @param {IterationData} data
+ * @returns {string}
+ */
+export function renderIterationEntry(data) {
+  const lines = [`## Iteration ${data.iteration}`, ""];
+  lines.push(`**Duration**: ${formatDuration(data.durationMs)}`);
+
+  if (data.coderSummary) {
+    lines.push("", "### Coder", data.coderSummary);
+  }
+
+  if (data.reviewerSummary || (data.blockingIssues && data.blockingIssues.length > 0)) {
+    lines.push("", "### Reviewer");
+    if (data.reviewerSummary) lines.push(data.reviewerSummary);
+    const blocks = formatBlockingIssues(data.blockingIssues);
+    if (blocks) {
+      lines.push("", blocks);
+    }
+  }
+
+  const sonarLine = formatSonarBlock(data);
+  if (sonarLine) {
+    lines.push("", "### Sonar", sonarLine);
+  }
+
+  if (data.testerSummary) lines.push("", "### Tester", data.testerSummary);
+  if (data.securitySummary) lines.push("", "### Security", data.securitySummary);
+
+  const solomonBlock = formatSolomonBlock(data.solomon);
+  if (solomonBlock) {
+    lines.push("", "### Solomon", solomonBlock);
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Append an iteration record to session._journalIterations.
+ * Creates the array if absent. Callers pass structured IterationData.
+ *
+ * @param {Object} session
+ * @param {IterationData} data
+ */
+export function recordIteration(session, data) {
+  if (!session || !data) return;
+  if (!Array.isArray(session._journalIterations)) session._journalIterations = [];
+  session._journalIterations.push(renderIterationEntry(data));
+}
+
+/**
+ * Build the full iterations.md content from recorded entries.
+ * Returns null when there are no iterations to render.
+ *
+ * @param {Object} session
+ * @returns {string|null}
+ */
+export function buildIterationsMarkdown(session) {
+  const entries = Array.isArray(session?._journalIterations) ? session._journalIterations : [];
+  if (entries.length === 0) return null;
+  const header = [
+    `# Session iterations — ${session.id || "(unknown)"}`,
+    "",
+    `_Generated at ${new Date().toISOString()}._`,
+    "",
+    `Total iterations: **${entries.length}**`,
+    "",
+    "---",
+    "",
+  ].join("\n");
+  return header + entries.join("---\n\n") + "\n";
+}
+
+/**
+ * Extract structured iteration data from a stageResults bundle + session state.
+ * The orchestrator produces stage results per role; this helper pulls the
+ * relevant fields into a single object suitable for recordIteration().
+ *
+ * @param {Object} args
+ * @param {number} args.iteration
+ * @param {number} args.durationMs
+ * @param {Object} args.stageResults
+ * @param {Object} [args.session]
+ * @returns {IterationData}
+ */
+export function extractIterationData({ iteration, durationMs, stageResults = {}, session = {} }) {
+  const coderSummary = stageResults.coder?.summary || stageResults.coder?.result?.summary;
+  const reviewerSummary = stageResults.reviewer?.summary;
+  const blockingIssues = stageResults.reviewer?.result?.blocking_issues
+    || stageResults.reviewer?.blocking_issues
+    || [];
+  const testerSummary = stageResults.tester?.summary;
+  const securitySummary = stageResults.security?.summary;
+  const sonarSummary = stageResults.sonar?.summary
+    || (stageResults.sonar?.openIssues != null ? `${stageResults.sonar.openIssues} open issue(s)` : undefined);
+  const sonarIssuesFound = stageResults.sonar?.issuesInitial ?? stageResults.sonar?.issuesFound;
+  const sonarIssuesResolved = stageResults.sonar?.issuesResolved;
+
+  // Solomon ruling for THIS iteration: match by iteration if the session
+  // tracks it; otherwise just take the latest ruling.
+  const rulings = Array.isArray(session.solomonRulings) ? session.solomonRulings : [];
+  const solomonRecord = rulings.find((r) => r.iteration === iteration) || rulings.at(-1);
+  const solomon = solomonRecord ? { ruling: solomonRecord.ruling, reasoning: solomonRecord.reasoning } : undefined;
+
+  return {
+    iteration,
+    durationMs,
+    coderSummary,
+    reviewerSummary,
+    blockingIssues,
+    sonarSummary,
+    sonarIssuesFound,
+    sonarIssuesResolved,
+    testerSummary,
+    securitySummary,
+    solomon,
+  };
+}