@karajan-family/code 4.21.0

package/src/roles/tool-correctness-judge-role.js

@@ -0,0 +1,78 @@
+// KJC-TSK-0375 — ToolCorrectnessJudgeRole.
+// Post-iteration LLM judge scoring how well a coder picked its tool calls.
+// PR1 ships role + tests; wiring lives in PR3.
+
+import { AgentRole } from "./agent-role.js";
+import { buildToolCorrectnessJudgePrompt } from "../prompts/tool-correctness-judge.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+
+const DEFAULT_THRESHOLD = 70;
+
+const clampScore = (n) => Number.isFinite(n) ? Math.max(0, Math.min(100, Math.round(n))) : null;
+
+const normalizeBreakdown = (b) => Array.isArray(b) ? b.map((x) => ({
+  tool: typeof x?.tool === "string" ? x.tool : "unknown",
+  args: x?.args && typeof x.args === "object" ? x.args : {},
+  correct: Boolean(x?.correct),
+  reason: typeof x?.reason === "string" ? x.reason.trim() : "",
+})) : [];
+
+export class ToolCorrectnessJudgeRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "tool-correctness-judge" });
+    this.threshold = opts?.threshold ?? this.config?.pipeline?.tool_judge?.threshold ?? DEFAULT_THRESHOLD;
+  }
+
+  resolveProvider() {
+    return this.config?.roles?.["tool-correctness-judge"]?.provider
+      || this.config?.roles?.reviewer?.provider
+      || this.config?.roles?.coder?.provider
+      || "claude";
+  }
+
+  extractInput(input) {
+    return { ...super.extractInput(input), toolCalls: Array.isArray(input?.toolCalls) ? input.toolCalls : [] };
+  }
+
+  async buildPrompt({ task, toolCalls }) {
+    return { prompt: buildToolCorrectnessJudgePrompt({ task, toolCalls, instructions: this.instructions }) };
+  }
+
+  parseOutput(raw) { return extractFirstJson(raw); }
+
+  buildSuccessResult(parsed, provider) {
+    const score = clampScore(parsed?.score);
+    return {
+      score,
+      summary: typeof parsed?.summary === "string" ? parsed.summary.trim() : "",
+      breakdown: normalizeBreakdown(parsed?.breakdown),
+      threshold: this.threshold,
+      lowQuality: score !== null && score < this.threshold,
+      provider,
+    };
+  }
+
+  buildSummary(parsed) {
+    const score = clampScore(parsed?.score);
+    if (score === null) return "Tool-judge: unparseable score";
+    return `Tool-judge: ${score}/100 (${score < this.threshold ? "LOW" : "OK"})`;
+  }
+
+  // Empty tool-call list = nothing to judge. Skip the LLM and report a
+  // neutral score so an absent transcript is never read as a failure.
+  async execute(input) {
+    const extracted = this.extractInput(input);
+    if (extracted.toolCalls.length === 0) {
+      return {
+        ok: true,
+        result: {
+          score: null, summary: "no tool calls captured (skipped)", breakdown: [],
+          threshold: this.threshold, lowQuality: false, provider: this.resolveProvider(), skipped: true,
+        },
+        summary: "Tool-judge: skipped (no calls)",
+        usage: null,
+      };
+    }
+    return super.execute(extracted);
+  }
+}

package/src/roles/triage-role.js

@@ -0,0 +1,99 @@
+import { AgentRole } from "./agent-role.js";
+import { buildTriagePrompt } from "../prompts/triage.js";
+import { VALID_TASK_TYPES } from "../guards/policy-resolver.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+
+const VALID_LEVELS = new Set(["trivial", "simple", "medium", "complex"]);
+const VALID_ROLES = new Set(["planner", "researcher", "refactorer", "reviewer", "tester", "security", "impeccable"]);
+const FALLBACK_TASK_TYPE = "sw";
+const FALLBACK_RESULT = { level: "medium", roles: ["reviewer"], taskType: FALLBACK_TASK_TYPE, shouldDecompose: false };
+
+function normalizeRoles(roles) {
+  if (!Array.isArray(roles)) return [];
+  return Array.from(new Set(roles.filter((role) => VALID_ROLES.has(role))));
+}
+
+function normalizeSubtasks(subtasks) {
+  if (!Array.isArray(subtasks)) return [];
+  return subtasks.map((s) => (typeof s === "string" ? s.trim() : "")).filter(Boolean).slice(0, 5);
+}
+
+function normalizeDomainHints(hints) {
+  if (!Array.isArray(hints)) return [];
+  return hints.map((h) => (typeof h === "string" ? h.trim().toLowerCase() : "")).filter(Boolean);
+}
+
+export class TriageRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "triage" });
+  }
+
+  async buildPrompt({ task }) {
+    return { prompt: buildTriagePrompt({ task, instructions: this.instructions }) };
+  }
+
+  parseOutput(raw) { return extractFirstJson(raw); }
+
+  buildSuccessResult(parsed, provider) {
+    const level = VALID_LEVELS.has(parsed.level) ? parsed.level : "medium";
+    const roles = normalizeRoles(parsed.roles);
+    const reasoning = String(parsed.reasoning || "").trim() || "No reasoning provided.";
+    const shouldDecompose = Boolean(parsed.shouldDecompose);
+    const subtasks = normalizeSubtasks(parsed.subtasks);
+    const taskType = VALID_TASK_TYPES.has(parsed.taskType) ? parsed.taskType : FALLBACK_TASK_TYPE;
+    const domainHints = normalizeDomainHints(parsed.domainHints);
+
+    const result = { level, roles, reasoning, taskType, domainHints, provider };
+    if (shouldDecompose && subtasks.length > 0) {
+      result.shouldDecompose = true;
+      result.subtasks = subtasks;
+    } else {
+      result.shouldDecompose = false;
+    }
+    return result;
+  }
+
+  buildSummary(parsed) {
+    const level = VALID_LEVELS.has(parsed.level) ? parsed.level : "medium";
+    const roles = normalizeRoles(parsed.roles);
+    const decomposeNote = parsed.shouldDecompose ? " — decomposition recommended" : "";
+    return `Triage: ${level} (${roles.length} role${roles.length === 1 ? "" : "s"})${decomposeNote}`;
+  }
+
+  handleParseNull(agentResult, provider) {
+    return this.degradedTriageResult({
+      agentResult, provider,
+      reason: "parse-null",
+      reasoning: "Unstructured output, using safe defaults.",
+      message: "[triage] LLM output was unstructured — falling back to defaults; the pipeline may skip optional roles.",
+    });
+  }
+
+  handleParseError(err, agentResult, provider) {
+    return this.degradedTriageResult({
+      agentResult, provider,
+      reason: "parse-error",
+      reasoning: `Failed to parse triage output (${err?.message || "unknown error"}), using safe defaults.`,
+      message: `[triage] Could not parse LLM output — falling back to defaults: ${err?.message || "unknown"}.`,
+    });
+  }
+
+  // Triage degradation is what made a complex task quietly run as
+  // `level: "medium", roles: ["reviewer"]` — researcher / architect /
+  // security / tester silently skipped. The fallback is preserved so
+  // the pipeline still moves, but the user (and any board / kj-tail
+  // listener) now learns it happened. result.degraded = true lets
+  // downstream code react if it wants.
+  // Same shape as before so downstream cost / event accounting is
+  // byte-identical; the only change is the loud logger.warn, which is
+  // what makes the silent degradation visible to the user / kj-tail.
+  degradedTriageResult({ agentResult, provider, reason: _reason, reasoning, message }) {
+    this.logger?.warn?.(message);
+    return {
+      ok: true,
+      result: { ...FALLBACK_RESULT, reasoning, provider, raw: agentResult.output },
+      summary: "Triage complete (fallback defaults)",
+      usage: agentResult.usage,
+    };
+  }
+}

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 ?? "").replaceAll(/\|/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 ?? "").replaceAll(/\|/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,
+  };
+}