karajan-code 4.70.4 → 5.0.0

package/src/roles/tester-role.js

@@ -1,235 +0,0 @@
-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.",
-  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
-  "Do NOT use any MCP tools. Focus only on evaluating test quality."
-].join(" ");
-
-/**
- * Map test framework to the command that runs tests with coverage.
- */
-const COVERAGE_COMMANDS = {
-  vitest: "npx vitest run --coverage --reporter=verbose 2>&1",
-  jest: "npx jest --coverage --verbose 2>&1",
-  mocha: "npx c8 mocha 2>&1",
-  playwright: "npx playwright test 2>&1",
-  pytest: "pytest --cov --tb=short 2>&1",
-  "go-test": "go test -cover -v ./... 2>&1",
-  "cargo-test": "cargo test --verbose 2>&1",
-  junit: "mvn test 2>&1",
-  rspec: "bundle exec rspec 2>&1",
-  phpunit: "vendor/bin/phpunit --coverage-text 2>&1",
-  "dotnet-test": "dotnet test --collect:\"XPlat Code Coverage\" 2>&1",
-  "dart-test": "dart test 2>&1",
-  // INF-B: the basic suite ALWAYS runs first; checkov is the additive deep
-  // scan. If checkov is missing this chain fails and the brief falls back to
-  // the basic suite alone (declared degradation, never green-by-omission).
-  "terraform-validate": "terraform init -backend=false -input=false 2>&1 && terraform validate 2>&1 && checkov -d . --compact --quiet 2>&1",
-  "helm-lint": "helm lint . 2>&1 && checkov -d . --compact --quiet 2>&1",
-  "kustomize-build": "kustomize build . > /dev/null && checkov -d . --compact --quiet 2>&1",
-  "ansible-lint": "ansible-lint 2>&1 && checkov -d . --compact --quiet 2>&1"
-};
-
-const TEST_COMMANDS = {
-  vitest: "npx vitest run --reporter=verbose 2>&1",
-  jest: "npx jest --verbose 2>&1",
-  mocha: "npx mocha 2>&1",
-  playwright: "npx playwright test 2>&1",
-  pytest: "pytest --tb=short 2>&1",
-  "go-test": "go test -v ./... 2>&1",
-  "cargo-test": "cargo test --verbose 2>&1",
-  junit: "mvn test 2>&1",
-  rspec: "bundle exec rspec 2>&1",
-  phpunit: "vendor/bin/phpunit 2>&1",
-  "dotnet-test": "dotnet test 2>&1",
-  "dart-test": "dart test 2>&1",
-  // INF-B (KJC-TSK-0759): infra suites — validity IS the test floor.
-  "terraform-validate": "terraform init -backend=false -input=false 2>&1 && terraform validate 2>&1",
-  "helm-lint": "helm lint . 2>&1",
-  "kustomize-build": "kustomize build . > /dev/null && echo kustomize build: OK",
-  "ansible-lint": "ansible-lint 2>&1"
-};
-
-export class TesterRole extends AgentRole {
-  constructor(opts) {
-    super({ ...opts, name: "tester" });
-  }
-
-  extractInput(input) {
-    if (typeof input === "string") return { task: input, diff: null, sonarIssues: null, pendingGherkinTests: null, shellTestResults: null };
-    return {
-      task: input?.task || this.context?.task || "",
-      diff: input?.diff || null,
-      sonarIssues: input?.sonarIssues || null,
-      // Tests-first Phase 3 (v2.7.5): the tester now has two extra inputs.
-      //   - pendingGherkinTests: HU-declared Gherkin scenarios that need
-      //     translation into executable code tests in the project's
-      //     framework. The tester writes the test files and includes them
-      //     in the suite run before computing verdict.
-      //   - shellTestResults: results of running the HU's shell-type
-      //     acceptance_tests (already run upstream, passed at this point).
-      //     Passed for context so the tester doesn't re-run them redundantly.
-      pendingGherkinTests: input?.pendingGherkinTests || null,
-      shellTestResults: input?.shellTestResults || null,
-      onOutput: input?.onOutput || null
-    };
-  }
-
-  async buildPrompt({ task, diff, sonarIssues, pendingGherkinTests, shellTestResults }) {
-    const projectDir = this.config?.projectDir || process.cwd();
-    const detection = await detectTestFramework(projectDir);
-
-    const sections = [SUBAGENT_PREAMBLE];
-    if (this.instructions) sections.push(this.instructions);
-
-    sections.push(
-      "You are a test quality gate. Your job is to EXECUTE the test suite, measure REAL coverage, and evaluate quality.",
-      "You MUST run the actual test command — do NOT guess or estimate results."
-    );
-
-    if (detection.hasTests && detection.framework) {
-      const coverageCmd = COVERAGE_COMMANDS[detection.framework];
-      const testCmd = TEST_COMMANDS[detection.framework];
-      // INF-B: infra suites have no node_modules — the step-0 contract is
-      // "the tool exists or you SAY which one is missing", never a fake green.
-      const step0 = detection.language === "infra"
-        ? "**Step 0**: Verify the SUITE tool is installed (`which terraform`/`helm`/`kustomize`/`ansible-lint`). If the suite tool is MISSING, do NOT fake a green: report it in `failures` with the exact install command and set tests_pass: false. `checkov` (the deep scan below) is OPTIONAL: if it is missing, run the basic suite as the fallback and SAY the deep scan was skipped (degraded, never green-by-omission)."
-        : "**Step 0**: If node_modules/ does not exist, run `npm install` (or `pnpm install`) first.";
-      sections.push(
-        `## Detected test framework: ${detection.framework} (${detection.language})`,
-        step0,
-        `**Step 1**: Run the test suite with coverage:`,
-        "```bash",
-        coverageCmd || testCmd,
-        "```",
-        "If the coverage command fails (missing dependency), fall back to:",
-        "```bash",
-        testCmd,
-        "```",
-        "**Step 2**: Parse the output to extract: pass/fail count, coverage percentages, any failures.",
-        "**Step 3**: Return a single JSON object with REAL numbers from the test output."
-      );
-    } else {
-      sections.push(
-        "## No test framework detected",
-        "**Step 0**: If package.json exists but node_modules/ does not, run `npm install` first.",
-        "**Step 1**: Look at package.json or project files to find test scripts.",
-        "**Step 2**: Try running `npm test` or detect the framework from config files.",
-        "**Step 3**: If tests exist, run them. If no tests exist, report tests_pass: false with verdict: 'fail'.",
-        "**Step 4**: Return a JSON object with your findings."
-      );
-    }
-
-    // Tests-first Phase 3 (v2.7.5): include the upstream shell-test results
-    // so the tester knows which part of the contract is already green.
-    if (Array.isArray(shellTestResults) && shellTestResults.length > 0) {
-      const passedCount = shellTestResults.filter((r) => r.passed).length;
-      sections.push(
-        "## Acceptance gate — shell tests",
-        `The HU's shell-type acceptance_tests already ran upstream: ${passedCount}/${shellTestResults.length} passed.`,
-        "Do NOT re-run them. Use the coverage/translation steps below to decide your verdict."
-      );
-    }
-
-    // Gherkin translation block — only when the HU carries Gherkin
-    // scenarios. Tester must produce real test files (in the detected
-    // framework's language) that encode Given/When/Then. This is how
-    // behaviour-level specs become enforceable.
-    if (Array.isArray(pendingGherkinTests) && pendingGherkinTests.length > 0) {
-      sections.push(
-        "## Gherkin acceptance tests to translate",
-        "These Gherkin scenarios are the HU's behavioural contract. They are NOT yet",
-        "executable — your job is to turn each one into a concrete test case in the",
-        "project's test framework, WRITE the test files, and INCLUDE them in the suite",
-        "run that determines your verdict.",
-        "",
-        "For each scenario below:",
-        "1. Pick the appropriate test file (use `target` hint if present; otherwise",
-        "   put the test next to the module it exercises).",
-        "2. Write a test that asserts the Given/When/Then as-is. Do NOT soften the",
-        "   assertion — if it's ambiguous, pick the stricter reading.",
-        "3. Make sure the test runs as part of the normal suite (no separate invocation).",
-        "",
-        "If ANY translated test fails on the current code, return verdict: \"fail\" with",
-        "a failing_scenarios array listing the scenarios that didn't pass. The coder",
-        "will iterate.",
-        ""
-      );
-      pendingGherkinTests.forEach((entry, i) => {
-        const content = typeof entry === "string" ? entry : entry?.content || "";
-        const target = entry && entry.file ? ` · target: \`${entry.file}\`` : "";
-        sections.push(
-          `### Scenario ${i + 1}${target}`,
-          "```gherkin",
-          content,
-          "```",
-          ""
-        );
-      });
-    }
-
-    sections.push(
-      "",
-      "Return ONLY a single valid JSON object:",
-      '{"tests_pass":boolean,"coverage":{"overall":number,"services":number,"utilities":number},"missing_scenarios":[string],"quality_issues":[string],"failing_scenarios":[string],"translated_scenarios":[string],"verdict":"pass"|"fail"}',
-      "",
-      "- coverage.overall MUST be a real number from the test runner output, NOT an estimate",
-      "- If coverage tool is not available, set coverage.overall to null (not 0, not a guess)",
-      "- tests_pass must reflect whether the actual test run succeeded",
-      "- failing_scenarios: when Gherkin was given, list the scenarios your translated tests CAUGHT as failing",
-      "- translated_scenarios: when Gherkin was given, list the scenarios you successfully turned into passing tests",
-      "- verdict MUST be \"fail\" if any translated scenario still fails (even if coverage is green)",
-      `## Task\n${task}`
-    );
-    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") };
-  }
-
-  parseOutput(raw) { return extractFirstJson(raw); }
-
-  isSuccessful(parsed) {
-    const verdict = parsed.verdict || (parsed.tests_pass ? "pass" : "fail");
-    return verdict === "pass";
-  }
-
-  buildSuccessResult(parsed, provider) {
-    const verdict = parsed.verdict || (parsed.tests_pass ? "pass" : "fail");
-    return {
-      tests_pass: Boolean(parsed.tests_pass),
-      coverage: parsed.coverage || {},
-      missing_scenarios: parsed.missing_scenarios || [],
-      quality_issues: parsed.quality_issues || [],
-      // Tests-first Phase 3: Gherkin translation outcomes.
-      failing_scenarios: Array.isArray(parsed.failing_scenarios) ? parsed.failing_scenarios : [],
-      translated_scenarios: Array.isArray(parsed.translated_scenarios) ? parsed.translated_scenarios : [],
-      verdict,
-      provider
-    };
-  }
-
-  buildSummary(parsed) {
-    const verdict = parsed.verdict || (parsed.tests_pass ? "pass" : "fail");
-    const coverage = parsed.coverage || {};
-    const coverageStr = coverage.overall != null ? `${coverage.overall}%` : "not measured";
-    const missingPart = parsed.missing_scenarios?.length ? `; ${parsed.missing_scenarios.length} missing scenario(s)` : "";
-    const qualityPart = parsed.quality_issues?.length ? `; ${parsed.quality_issues.length} quality issue(s)` : "";
-    const failingPart = parsed.failing_scenarios?.length ? `; ${parsed.failing_scenarios.length} failing scenario(s)` : "";
-    const translatedPart = parsed.translated_scenarios?.length ? `; ${parsed.translated_scenarios.length} scenario(s) translated` : "";
-    return `Verdict: ${verdict}; Coverage: ${coverageStr}${translatedPart}${failingPart}${missingPart}${qualityPart}`;
-  }
-}

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

@@ -1,78 +0,0 @@
-// 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

@@ -1,99 +0,0 @@
-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

@@ -1,200 +0,0 @@
-/**
- * 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 || "",
-  });
-}