@karajan-family/code 4.21.0

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

@@ -0,0 +1,320 @@
+/**
+ * Executive session summary (`summary.md`) — the entry point to the journal
+ * directory. Pulls together every useful signal from the session into a
+ * single scannable Markdown page with links to the rest of the journal.
+ *
+ * Acceptance criterion (KJC-TSK-0289):
+ *   summary.md contains: task, result (approved/rejected/paused), iterations,
+ *   duration, budget, stages + status, list of journal files, commits.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * @typedef {Object} SummaryInput
+ * @property {string} sessionId
+ * @property {string} task
+ * @property {"APPROVED"|"REJECTED"|"PAUSED"|"FAILED"|string} result
+ * @property {number} iterations
+ * @property {number} durationMs
+ * @property {{ total_cost_usd?: number, total_tokens?: number, total_cached_tokens?: number, breakdown_by_role?: Object }} [budget]
+ * @property {Record<string, { ok?: boolean, summary?: string }>} [stages]
+ * @property {Array<{ hash?: string, message?: string, date?: string, author?: string }>} [commits]
+ * @property {string[]} [files]                    - names of other journal files in the same dir
+ * @property {string} [startedAt]                  - ISO timestamp (optional, auto-derived if absent)
+ * @property {string} [finishedAt]                 - ISO timestamp (optional)
+ * @property {number} [solomonInvocations]
+ * @property {number} [brainDecisions]
+ * @property {Object} [skills]                        - skill sources used this session (KJC-TSK-0327)
+ * @property {Object} [skills.addyosmani]             - { available, action, resolvedSlugs, reason }
+ * @property {string[]} [skills.installed]            - OpenSkills installed this run (session.autoInstalledSkills)
+ * @property {string[]} [skills.recommended]          - wouldHaveUsed when OpenSkills CLI missing
+ */
+
+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;
+  if (m < 60) return `${m}m ${rs}s`;
+  const h = Math.floor(m / 60);
+  const rm = m % 60;
+  return `${h}h ${rm}m ${rs}s`;
+}
+
+function formatBudget(budget) {
+  if (!budget) return "—";
+  const cost = Number(budget.total_cost_usd ?? 0);
+  const tokens = Number(budget.total_tokens ?? 0);
+  const costStr = `$${cost.toFixed(2)}`;
+  const tokStr = tokens > 0 ? `${tokens.toLocaleString("en-US")} tokens` : "—";
+  return `${costStr} · ${tokStr}`;
+}
+
+function resultBadge(result) {
+  const r = String(result || "").toUpperCase();
+  const map = {
+    APPROVED: "✅ APPROVED",
+    REJECTED: "❌ REJECTED",
+    PAUSED: "⏸ PAUSED",
+    FAILED: "❌ FAILED",
+  };
+  return map[r] || r;
+}
+
+function renderStagesTable(stages) {
+  if (!stages || Object.keys(stages).length === 0) return "_No stages recorded._";
+  const header = "| Stage | Status | Summary |\n|---|---|---|";
+  const rows = Object.entries(stages).map(([name, stageResult]) => {
+    const ok = stageResult?.ok !== false;
+    const status = ok ? "✅ pass" : "❌ fail";
+    const summary = esc(stageResult?.summary || "").slice(0, 120);
+    return `| \`${esc(name)}\` | ${status} | ${summary} |`;
+  });
+  return [header, ...rows].join("\n");
+}
+
+function renderCommits(commits) {
+  if (!Array.isArray(commits) || commits.length === 0) return "_No commits in this session._";
+  return commits
+    .map((c) => {
+      const hash = (c.hash || "").slice(0, 7) || "?";
+      return `- \`${hash}\` ${esc(c.message || "(no message)")}`;
+    })
+    .join("\n");
+}
+
+function renderBreakdownByRole(breakdown) {
+  if (!breakdown || typeof breakdown !== "object") return null;
+  const entries = Object.entries(breakdown)
+    .map(([role, m]) => ({
+      role,
+      tokens: Number(m?.total_tokens || 0),
+      cost: Number(m?.total_cost_usd || 0),
+    }))
+    .filter((e) => e.tokens > 0 || e.cost > 0);
+  if (entries.length === 0) return null;
+  const rows = entries
+    .sort((a, b) => b.cost - a.cost)
+    .map((e) => `| \`${esc(e.role)}\` | ${e.tokens.toLocaleString("en-US")} | $${e.cost.toFixed(4)} |`);
+  return ["| Role | Tokens | Cost |", "|---|---|---|", ...rows].join("\n");
+}
+
+/**
+ * Render the Cache hits section (Φ0-F, KJC-TSK-0524). Shows how many input
+ * tokens were served from provider-side prompt caches, per role, plus a
+ * conservative dollar savings estimate.
+ *
+ * Savings formula: cached tokens are billed at ~10% of the input rate (the
+ * Anthropic/OpenAI convention). Per role:
+ *   savings_usd ≈ cost_usd * (cached_tokens / tokens_in) * 0.9
+ * The estimate is approximate (output tokens also contribute to cost_usd)
+ * and labelled with `~$` so users don't read it as exact.
+ *
+ * Returns:
+ *   - null when no budget data is available
+ *   - "cold run" placeholder when cached == 0 across all roles
+ *   - Markdown table sorted by cached tokens desc when there is cache activity
+ */
+function renderCacheHits(budget) {
+  if (!budget) return null;
+  const totalCached = Number(budget.total_cached_tokens ?? 0);
+  const breakdown = budget.breakdown_by_role || {};
+  const entries = Object.entries(breakdown)
+    .map(([role, m]) => ({
+      role,
+      cached: Number(m?.cached_tokens || 0),
+      tokens_in: Number(m?.tokens_in || 0),
+      cost: Number(m?.total_cost_usd || 0),
+    }))
+    .filter((e) => e.cached > 0);
+
+  if (totalCached === 0 && entries.length === 0) {
+    return "_Cache hits: 0 tokens (cold run)._";
+  }
+
+  const rows = entries
+    .sort((a, b) => b.cached - a.cached)
+    .map((e) => {
+      const ratio = e.tokens_in > 0 ? (e.cached / e.tokens_in) * 100 : 0;
+      const savings = e.tokens_in > 0 ? e.cost * (e.cached / e.tokens_in) * 0.9 : 0;
+      return `| \`${esc(e.role)}\` | ${e.cached.toLocaleString("en-US")} | ${ratio.toFixed(1)}% | ~$${savings.toFixed(4)} |`;
+    });
+  const header = "| Role | Cached tokens | Ratio (cached/in) | Est. savings |\n|---|---|---|---|";
+  return [
+    `**Total cached**: ${totalCached.toLocaleString("en-US")} tokens`,
+    "",
+    header,
+    ...rows,
+  ].join("\n");
+}
+
+/**
+ * Render the Skills section: which process skills (addyosmani) were resolved
+ * for the task, which OpenSkills were installed, and which skills would have
+ * helped but couldn't be installed (graceful-degradation path).
+ *
+ * Returns null when no skill activity happened (no addyosmani, no installs,
+ * no recommendations) so the section is elided.
+ */
+function renderSkills(skills) {
+  if (!skills || typeof skills !== "object") return null;
+  const addy = skills.addyosmani;
+  const installed = Array.isArray(skills.installed) ? skills.installed : [];
+  const recommended = Array.isArray(skills.recommended) ? skills.recommended : [];
+
+  const hasAddy = addy && (addy.available === true || addy.available === false);
+  if (!hasAddy && installed.length === 0 && recommended.length === 0) return null;
+
+  const lines = [];
+
+  if (hasAddy) {
+    if (addy.available) {
+      const action = addy.action || "ready";
+      const slugs = Array.isArray(addy.resolvedSlugs) ? addy.resolvedSlugs : [];
+      lines.push(`- **addyosmani/agent-skills** (process, 1st source): ${esc(action)}` +
+        (slugs.length > 0 ? ` — resolved slugs: ${slugs.map((s) => `\`${esc(s)}\``).join(", ")}` : " — no role/task-specific slugs resolved"));
+    } else {
+      const reason = addy.reason ? ` — ${esc(addy.reason)}` : "";
+      lines.push(`- **addyosmani/agent-skills**: unavailable${reason}`);
+    }
+  }
+
+  if (installed.length > 0) {
+    lines.push(`- **OpenSkills installed**: ${installed.map((s) => `\`${esc(s)}\``).join(", ")}`);
+  }
+
+  if (recommended.length > 0) {
+    lines.push(`- **OpenSkills recommended** (CLI missing, would-have-used): ${recommended.map((s) => `\`${esc(s)}\``).join(", ")}`);
+  }
+
+  return lines.join("\n");
+}
+
+function renderJournalLinks(files) {
+  if (!Array.isArray(files) || files.length === 0) return "_No additional journal files._";
+  return files.map((f) => `- [${esc(f)}](./${f})`).join("\n");
+}
+
+/**
+ * Build the summary.md content.
+ *
+ * @param {SummaryInput} input
+ * @returns {string}
+ */
+export function buildSummaryMarkdown(input) {
+  const sessionId = input.sessionId || "(unknown)";
+  const result = resultBadge(input.result);
+  const startedAt = input.startedAt || "(unknown)";
+  const finishedAt = input.finishedAt || new Date().toISOString();
+
+  const sections = [
+    `# Session summary — ${sessionId}`,
+    "",
+    `- **Result**: ${result}`,
+    `- **Task**: ${esc(input.task || "(no task)")}`,
+    `- **Iterations**: ${input.iterations ?? 0}`,
+    `- **Duration**: ${formatDuration(input.durationMs)}`,
+    `- **Budget**: ${formatBudget(input.budget)}`,
+    `- **Started**: ${startedAt}`,
+    `- **Finished**: ${finishedAt}`,
+  ];
+
+  if (Number.isFinite(input.brainDecisions) && input.brainDecisions > 0) {
+    sections.push(`- **Brain decisions**: ${input.brainDecisions}`);
+  }
+  if (Number.isFinite(input.solomonInvocations) && input.solomonInvocations > 0) {
+    sections.push(`- **Solomon invocations**: ${input.solomonInvocations}`);
+  }
+
+  sections.push("", "---", "", "## Stages", "", renderStagesTable(input.stages));
+
+  const breakdown = renderBreakdownByRole(input.budget?.breakdown_by_role);
+  if (breakdown) {
+    sections.push("", "## Budget breakdown (by role)", "", breakdown);
+  }
+
+  const cacheHitsSection = renderCacheHits(input.budget);
+  if (cacheHitsSection) {
+    sections.push("", "## Cache hits", "", cacheHitsSection);
+  }
+
+  const skillsSection = renderSkills(input.skills);
+  if (skillsSection) {
+    sections.push("", "## Skills Used", "", skillsSection);
+  }
+
+  sections.push("", "## Commits", "", renderCommits(input.commits));
+
+  // KJC-TSK-0376 — plan adherence metric (deepeval-inspired). Only
+  // rendered when the run executed against a known plan and the
+  // calculation produced a non-null score (a run with no commits or
+  // no files changed yields nulls everywhere → omit the section).
+  const planAdherenceSection = renderPlanAdherence(input.planAdherence);
+  if (planAdherenceSection) {
+    sections.push("", "## Plan adherence", "", planAdherenceSection);
+  }
+
+  sections.push("", "## Journal files", "", renderJournalLinks(input.files));
+
+  return sections.join("\n") + "\n";
+}
+
+function renderPlanAdherence(planAdherence) {
+  if (!planAdherence || typeof planAdherence !== "object") return "";
+  if (planAdherence.score === null || planAdherence.score === undefined) return "";
+  const lines = [`**Score**: ${planAdherence.score}/100`, ""];
+  const breakdown = planAdherence.breakdown || {};
+  lines.push("| Component | Score | Weight |");
+  lines.push("| --- | --- | --- |");
+  const rows = [
+    ["Commit attribution", breakdown.commit_attribution, "40%"],
+    ["Acceptance tests",   breakdown.acceptance_tests,   "30%"],
+    ["Scope discipline",   breakdown.scope_discipline,   "20%"],
+    ["Dependency order",   breakdown.dependency_order,   "10%"],
+  ];
+  for (const [label, value, weight] of rows) {
+    const cell = value === null || value === undefined ? "n/a" : `${value}/100`;
+    lines.push(`| ${label} | ${cell} | ${weight} |`);
+  }
+  const huScores = Array.isArray(planAdherence.hu_scores) ? planAdherence.hu_scores : [];
+  if (huScores.length > 0) {
+    const unattributed = huScores.filter((h) => !h.attributed);
+    if (unattributed.length > 0) {
+      lines.push("", `_${unattributed.length} HU(s) without an attributed commit:_`);
+      for (const h of unattributed) {
+        lines.push(`- \`${h.huId}\``);
+      }
+    }
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Write summary.md to the given journal directory. Always writes (the file
+ * is the entry point; even a barebones session should have one).
+ *
+ * @param {string} journalDir
+ * @param {SummaryInput} input
+ * @param {{ logger?: Object }} [options]
+ * @returns {Promise<{ written: boolean, path: string|null }>}
+ */
+export async function writeSummaryJournal(journalDir, input, options = {}) {
+  const filePath = path.join(journalDir, "summary.md");
+  try {
+    await fs.mkdir(journalDir, { recursive: true });
+    await fs.writeFile(filePath, buildSummaryMarkdown(input), "utf8");
+    options.logger?.info?.(`Wrote session summary: ${filePath}`);
+    return { written: true, path: filePath };
+  } catch (err) {
+    options.logger?.warn?.(`Failed to write session summary (non-blocking): ${err.message}`);
+    return { written: false, path: null };
+  }
+}

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

@@ -0,0 +1,164 @@
+/**
+ * Build a directory-grouped tree view of files affected during the session,
+ * rendered as `.reviews/{sessionId}/tree.txt`.
+ *
+ * Acceptance criterion (KJC-TSK-0288):
+ *   - Given a kj run that modifies files, when the session finishes, then
+ *     tree.txt contains the tree of affected files (modified/added/deleted)
+ *     grouped by directory, generated from `git diff --name-status` against
+ *     the base ref.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { runCommand } from "../../utils/process.js";
+
+const STATUS_LABELS = {
+  M: "modified",
+  A: "added",
+  D: "deleted",
+  R: "renamed",
+  C: "copied",
+  T: "typechange",
+  U: "unmerged",
+};
+
+/**
+ * @typedef {Object} DiffEntry
+ * @property {string} file    - path relative to repo root
+ * @property {string} status  - "modified" | "added" | "deleted" | ...
+ */
+
+/**
+ * Parse `git diff --name-status` output into structured entries.
+ *
+ * @param {string} rawDiff
+ * @returns {DiffEntry[]}
+ */
+export function parseNameStatus(rawDiff) {
+  if (!rawDiff || !rawDiff.trim()) return [];
+  const entries = [];
+  for (const line of rawDiff.split("\n")) {
+    if (!line.trim()) continue;
+    const parts = line.split("\t");
+    const status = parts[0];
+    // Renames and copies report "R<score>\told\tnew". Take the new path.
+    const file = parts.length >= 3 ? parts[2] : parts[1];
+    if (!status || !file) continue;
+    const key = status[0];
+    const label = STATUS_LABELS[key] || "other";
+    entries.push({ file, status: label });
+  }
+  return entries;
+}
+
+/**
+ * Group entries into a nested directory tree.
+ * Each node is { name, children: Map<string, node>, entries: DiffEntry[] }.
+ *
+ * @param {DiffEntry[]} entries
+ * @returns {{name:string, children:Map<string, any>, files:DiffEntry[]}}
+ */
+export function buildTree(entries) {
+  const root = { name: "", children: new Map(), files: [] };
+  for (const entry of entries) {
+    const parts = entry.file.split("/");
+    let node = root;
+    for (let i = 0; i < parts.length - 1; i++) {
+      const dir = parts[i];
+      if (!node.children.has(dir)) {
+        node.children.set(dir, { name: dir, children: new Map(), files: [] });
+      }
+      node = node.children.get(dir);
+    }
+    node.files.push({ file: parts.at(-1), status: entry.status });
+  }
+  return root;
+}
+
+/**
+ * Render a tree node as indented text. Directories come before files at each
+ * level; both are sorted alphabetically (case-insensitive).
+ */
+function renderNode(node, depth, lines) {
+  const indent = "  ".repeat(depth);
+  const dirs = Array.from(node.children.values()).sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: "base" }));
+  for (const dir of dirs) {
+    lines.push(`${indent}${dir.name}/`);
+    renderNode(dir, depth + 1, lines);
+  }
+  const files = [...node.files].sort((a, b) => a.file.localeCompare(b.file, undefined, { sensitivity: "base" }));
+  for (const f of files) {
+    lines.push(`${indent}${f.file} [${f.status}]`);
+  }
+}
+
+/**
+ * Render the tree as a self-describing text document.
+ * Returns null when there are no entries.
+ *
+ * @param {DiffEntry[]} entries
+ * @returns {string|null}
+ */
+export function renderTree(entries) {
+  if (!entries || entries.length === 0) return null;
+  const tree = buildTree(entries);
+  const lines = ["# Affected files (grouped by directory)", ""];
+  renderNode(tree, 0, lines);
+  lines.push("");
+
+  // Summary counts at the bottom for quick scanning.
+  const counts = entries.reduce((acc, e) => {
+    acc[e.status] = (acc[e.status] || 0) + 1;
+    return acc;
+  }, {});
+  const summary = Object.entries(counts)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([status, n]) => `${n} ${status}`)
+    .join(", ");
+  lines.push(`Total: ${entries.length} file${entries.length === 1 ? "" : "s"} — ${summary}`);
+  return lines.join("\n");
+}
+
+/**
+ * Run `git diff --name-status <baseRef>...HEAD` and return structured entries.
+ * Returns [] if git exits with an error or produces no output.
+ *
+ * @param {string} baseRef
+ * @returns {Promise<DiffEntry[]>}
+ */
+export async function collectAffectedFiles(baseRef) {
+  if (!baseRef) return [];
+  try {
+    const result = await runCommand("git", ["diff", "--name-status", `${baseRef}...HEAD`]);
+    if (result.exitCode !== 0) return [];
+    return parseNameStatus(result.stdout || "");
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * High-level: generate the tree content and persist it to `tree.txt` under
+ * the given journal directory. Returns `{ written, path }`.
+ *
+ * @param {string} journalDir
+ * @param {string} baseRef
+ * @param {{ logger?: Object }} [options]
+ * @returns {Promise<{ written: boolean, path: string|null }>}
+ */
+export async function writeTreeJournal(journalDir, baseRef, options = {}) {
+  const entries = await collectAffectedFiles(baseRef);
+  const content = renderTree(entries);
+  if (!content) return { written: false, path: null };
+  const filePath = path.join(journalDir, "tree.txt");
+  try {
+    await fs.mkdir(journalDir, { recursive: true });
+    await fs.writeFile(filePath, content + "\n", "utf8");
+    options.logger?.info?.(`Wrote file tree journal: ${filePath}`);
+    return { written: true, path: filePath };
+  } catch (err) {
+    options.logger?.warn?.(`Failed to write tree journal (non-blocking): ${err.message}`);
+    return { written: false, path: null };
+  }
+}

package/src/session/journal/write-all.js

@@ -0,0 +1,89 @@
+/**
+ * Session-journal writer shared by every terminal path (KJC-BUG-0084).
+ *
+ * Pre-fix, the iterations/decisions/tree/summary block lived inline in
+ * finalizeApprovedSession(), so a run that died on a stage error
+ * (sonar_repeat, gh pr create failure, thrown stage) left only triage.md
+ * behind — the Cache hits table, the budget breakdown and the commit list
+ * vanished exactly on the runs where they matter most. This module is the
+ * single writer; the approved path calls it with its enriched extras and
+ * flow-runner's `finally` calls it best-effort for every other ending.
+ *
+ * Never throws: a journal failure must not mask the run's real result.
+ */
+
+import { writeIterationsJournal } from "../../orchestrator/session-journal.js";
+import { listCommitsBetween } from "../../utils/git.js";
+import { writeDecisionsJournal } from "./decisions-writer.js";
+import { writeTreeJournal } from "./tree-writer.js";
+import { writeSummaryJournal } from "./summary-writer.js";
+
+/**
+ * Write iterations.md, decisions.md, tree.txt and summary.md for a session.
+ *
+ * @param {object} args
+ * @param {object} args.session - live session (needs _journalDir to write)
+ * @param {{info?: Function, warn?: Function}} [args.logger]
+ * @param {string} [args.result] - summary badge: APPROVED | FAILED | STOPPED…
+ * @param {number} [args.iterations]
+ * @param {object|null} [args.budget] - budgetSummary() snapshot
+ * @param {object} [args.stages] - stageResults map
+ * @param {Array}  [args.commits] - precomputed commit list; computed from
+ *   session_start_sha when omitted
+ * @param {object|null} [args.planAdherence]
+ * @returns {Promise<{written: boolean, reason?: string}>}
+ */
+export async function writeSessionJournal({ session, logger, result = "APPROVED", iterations = 0, budget = null, stages = {}, commits = null, planAdherence = null }) {
+  const journalDir = session?._journalDir;
+  if (!journalDir) return { written: false, reason: "no journal dir" };
+
+  try {
+    await writeIterationsJournal(journalDir, session._journalIterations || []);
+    const decisionsResult = await writeDecisionsJournal(session, { journalDir, logger });
+    const treeResult = await writeTreeJournal(journalDir, session.session_start_sha, { logger });
+
+    const journalFiles = [...(session._journalFiles || [])];
+    if (session._journalIterations?.length) journalFiles.push("iterations.md");
+    if (decisionsResult.written) journalFiles.push("decisions.md");
+    if (treeResult.written) journalFiles.push("tree.txt");
+
+    // Commit range from session start so the summary shows every commit
+    // the run produced, not just the post-loop scaffold (2026-05-07
+    // dogfooding). try/catch tolerates promise rejection AND a sync
+    // undefined return from a resetAllMocks-stripped test mock.
+    let summaryCommits = Array.isArray(commits) ? commits : null;
+    if (!summaryCommits) {
+      try { summaryCommits = (await listCommitsBetween(session.head_at_start || session.session_start_sha)) || []; }
+      catch { summaryCommits = []; }
+    }
+
+    const startedAt = session._startedAt ? new Date(session._startedAt).toISOString() : undefined;
+    await writeSummaryJournal(journalDir, {
+      task: session.task,
+      result,
+      sessionId: session.id,
+      iterations,
+      durationMs: Date.now() - (session._startedAt || Date.now()),
+      budget,
+      stages,
+      commits: summaryCommits,
+      files: journalFiles,
+      startedAt,
+      finishedAt: new Date().toISOString(),
+      brainDecisions: Array.isArray(session.brainDecisions) ? session.brainDecisions.length : 0,
+      solomonInvocations: Array.isArray(session.solomonRulings) ? session.solomonRulings.length : 0,
+      skills: {
+        addyosmani: session.addyosmaniSkills,
+        installed: session.autoInstalledSkills,
+        recommended: session.skillsRecommended,
+      },
+      planAdherence,
+    }, { logger });
+    session._journalWritten = true;
+    logger?.info?.(`Session journal written to ${journalDir}`);
+    return { written: true };
+  } catch (err) {
+    logger?.warn?.(`Journal write failed (non-blocking): ${err.message}`);
+    return { written: false, reason: err.message };
+  }
+}