karajan-code 2.10.2 → 2.12.0

package/src/git/hu-automation.js

@@ -41,6 +41,34 @@ export function resolveHuBase(story, huBranches, baseBranch) {
   return baseBranch;
 }
 
+/**
+ * Resolve to an actually-existing local ref. Tries the preferred branch
+ * first, then `main` and `master`, then plain `HEAD` as last resort.
+ *
+ * Why: N6 plan-flow dogfooding (2026-05-07) on a `git init -q` repo
+ * with `init.defaultBranch=master` produced 7 identical warnings:
+ *   `failed to create branch feat/...-001 from main:
+ *    fatal: 'main' is not a commit and a branch can't be created`.
+ * Every HU then fell back to running on the original branch, which
+ * defeats the per-HU isolation the sub-pipeline was supposed to give.
+ *
+ * The configured base_branch is honoured when it exists; otherwise we
+ * pick the most likely default. HEAD always exists once the repo has
+ * any commit, so the fallback never throws past the gate.
+ *
+ * @param {string} preferred
+ * @returns {Promise<string>}
+ */
+async function resolveExistingBranchRef(preferred) {
+  const candidates = [preferred, "main", "master", "HEAD"]
+    .filter((c, i, arr) => c && arr.indexOf(c) === i); // unique, truthy
+  for (const ref of candidates) {
+    const probe = await runCommand("git", ["rev-parse", "--verify", "--quiet", ref], {});
+    if (probe.exitCode === 0) return ref;
+  }
+  return preferred; // give up; caller will surface the original error
+}
+
 /**
  * Create a branch for an HU starting from its resolved base.
  * Returns the branch name created (or null if git automation is disabled).
@@ -57,17 +85,21 @@ export async function prepareHuBranch({ story, huBranches, config, logger }) {
     return null;
   }
   const baseBranch = resolveHuBase(story, huBranches, config.base_branch || "main");
+  const effectiveBase = await resolveExistingBranchRef(baseBranch);
+  if (effectiveBase !== baseBranch) {
+    logger.info(`HU git: configured base '${baseBranch}' not found locally — using '${effectiveBase}' instead`);
+  }
   const prefix = config.git?.branch_prefix || "feat/";
   const branchName = buildHuBranchName(prefix, story);
 
   // Checkout from the resolved base. Use `git checkout -B` to overwrite if rerun.
-  const res = await runCommand("git", ["checkout", "-B", branchName, baseBranch], {});
+  const res = await runCommand("git", ["checkout", "-B", branchName, effectiveBase], {});
   if (res.exitCode !== 0) {
-    logger.warn(`HU git: failed to create branch ${branchName} from ${baseBranch}: ${res.stderr}`);
+    logger.warn(`HU git: failed to create branch ${branchName} from ${effectiveBase}: ${res.stderr}`);
     return null;
   }
   huBranches.set(story.id, branchName);
-  logger.info(`HU ${story.id}: branch '${branchName}' from '${baseBranch}'`);
+  logger.info(`HU ${story.id}: branch '${branchName}' from '${effectiveBase}'`);
   return branchName;
 }
 

package/src/golden/asserter.js

@@ -0,0 +1,90 @@
+/**
+ * Golden tasks asserter (KJC-TSK-0374). Parses a `summary.md` produced
+ * by a real `kj run` and compares it against a GoldenTask's structural
+ * expectations. Pure: no I/O, no subprocess. Subprocess driver lands
+ * in PR-3a; the 3 fixtures + baseline + spec land in PR-3b.
+ *
+ * Three of the five assertion families live here (the ones derivable
+ * from summary.md alone): expected_commits_min, expected_audit_status,
+ * expected_plan_adherence_min. expected_test_files and
+ * allowed_loc_range need filesystem access — PR-3a wires those.
+ */
+
+const COMMIT_LINE = /^- `([^`]+)`\s+(.*)$/;
+const SCORE_LINE = /^\*\*Score\*\*:\s*(\d+)\s*\/\s*100/m;
+const AUDIT_ROW = /^\|\s*`audit`\s*\|\s*([^|]+?)\s*\|/m;
+
+function extractSection(content, heading) {
+  const re = new RegExp(`^## ${heading}\\s*$([\\s\\S]*?)(?=^## |\\Z)`, "m");
+  const m = content.match(re);
+  return m ? m[1].trim() : "";
+}
+
+function parseCommits(content) {
+  const section = extractSection(content, "Commits");
+  if (!section || /No commits/.test(section)) return [];
+  return section
+    .split("\n")
+    .map((line) => line.match(COMMIT_LINE))
+    .filter(Boolean)
+    .map(([, hash, message]) => ({ hash, message }));
+}
+
+function parseAuditStatus(content) {
+  const m = content.match(AUDIT_ROW);
+  if (!m) return null;
+  const cell = m[1];
+  if (/✅|pass/i.test(cell)) return "pass";
+  if (/❌|fail/i.test(cell)) return "fail";
+  if (/⚠|warn/i.test(cell)) return "warning";
+  return null;
+}
+
+function parsePlanAdherence(content) {
+  const section = extractSection(content, "Plan adherence");
+  if (!section) return null;
+  const m = section.match(SCORE_LINE);
+  if (!m) return null;
+  const score = Number(m[1]);
+  return Number.isFinite(score) ? score : null;
+}
+
+export function parseSummary(content) {
+  const text = String(content || "");
+  return {
+    commits: parseCommits(text),
+    auditStatus: parseAuditStatus(text),
+    planAdherenceScore: parsePlanAdherence(text),
+  };
+}
+
+export function assertFromSummary(task, parsed) {
+  const failures = [];
+
+  const fail = (kind, expected, actual, message) => failures.push({ kind, expected, actual, message });
+
+  if (parsed.commits.length < task.expected_commits_min) {
+    fail("commits_min", `>= ${task.expected_commits_min}`, parsed.commits.length,
+      `expected at least ${task.expected_commits_min} commit(s); got ${parsed.commits.length}`);
+  }
+
+  if (parsed.auditStatus !== task.expected_audit_status) {
+    const got = parsed.auditStatus === null ? "no audit row in summary" : `"${parsed.auditStatus}"`;
+    fail("audit_status", task.expected_audit_status, parsed.auditStatus,
+      `expected audit "${task.expected_audit_status}"; got ${got}`);
+  }
+
+  if (typeof task.expected_plan_adherence_min === "number") {
+    const score = parsed.planAdherenceScore;
+    const min = task.expected_plan_adherence_min;
+    if (score === null) {
+      fail("plan_adherence_missing", `>= ${min}`, null,
+        `expected plan adherence >= ${min}; summary has no Plan adherence section`);
+    } else if (score < min) {
+      fail("plan_adherence_below", `>= ${min}`, score,
+        `expected plan adherence >= ${min}; got ${score}`);
+    }
+  }
+
+  return { ok: failures.length === 0, failures };
+}

package/src/golden/loader.js

@@ -0,0 +1,52 @@
+/**
+ * Golden tasks loader (KJC-TSK-0374). Reads + validates JSON files
+ * under a directory; aggregates errors; rejects duplicate ids.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { safeParseGoldenTask } from "./schema.js";
+
+export async function loadGoldenTasks(dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true }).catch((err) => {
+    throw new Error(`golden tasks directory not readable: ${dir} (${err.code || err.message})`);
+  });
+  const jsonFiles = entries
+    .filter((e) => e.isFile() && e.name.endsWith(".json"))
+    .map((e) => path.join(dir, e.name))
+    .sort();
+
+  const tasks = [];
+  const errors = [];
+  const seenIds = new Map();
+
+  for (const filePath of jsonFiles) {
+    let raw;
+    try {
+      const content = await fs.readFile(filePath, "utf8");
+      raw = JSON.parse(content);
+    } catch (err) {
+      errors.push(`${path.basename(filePath)}: invalid JSON (${err.message})`);
+      continue;
+    }
+    const result = safeParseGoldenTask(raw);
+    if (!result.ok) {
+      const summary = result.issues.map((iss) => `  - ${iss.path || "(root)"}: ${iss.message}`).join("\n");
+      errors.push(`${path.basename(filePath)}:\n${summary}`);
+      continue;
+    }
+    const existing = seenIds.get(result.task.id);
+    if (existing) {
+      errors.push(`${path.basename(filePath)}: duplicate id "${result.task.id}" (also in ${existing})`);
+      continue;
+    }
+    seenIds.set(result.task.id, path.basename(filePath));
+    tasks.push(result.task);
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`golden tasks failed validation:\n${errors.join("\n")}`);
+  }
+
+  return { tasks };
+}

package/src/golden/runner.js

@@ -0,0 +1,92 @@
+/**
+ * Golden tasks subprocess runner (KJC-TSK-0374). Spawns `kj run` in
+ * a sandbox dir, reads back summary.md, evaluates the schema's
+ * filesystem-dependent assertions (expected_test_files, allowed_loc_range),
+ * and merges them with `assertFromSummary` into a single result.
+ *
+ * The kj subprocess + diff calls are injected so unit tests can drive
+ * the runner without spawning anything (real e2e is opt-in via PR-3b).
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { runCommand as defaultRun } from "../utils/process.js";
+import { parseSummary, assertFromSummary } from "./asserter.js";
+
+async function findLatestSummary(workDir) {
+  const journalRoot = path.join(workDir, ".karajan", "sessions");
+  const sessions = await fs.readdir(journalRoot).catch(() => []);
+  if (sessions.length === 0) return null;
+  const stats = await Promise.all(sessions.map(async (id) => {
+    const file = path.join(journalRoot, id, "summary.md");
+    const stat = await fs.stat(file).catch(() => null);
+    return stat ? { file, mtimeMs: stat.mtimeMs } : null;
+  }));
+  const valid = stats.filter(Boolean).sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return valid[0]?.file ?? null;
+}
+
+async function findMissingTestFiles(workDir, paths) {
+  const checks = await Promise.all(paths.map(async (rel) =>
+    [rel, await fs.stat(path.join(workDir, rel)).then(() => true).catch(() => false)]));
+  return checks.filter(([, ok]) => !ok).map(([rel]) => rel);
+}
+
+async function totalLocSince(workDir, baseSha, run) {
+  const res = await run("git", ["diff", "--numstat", `${baseSha}..HEAD`], { cwd: workDir }).catch(() => null);
+  if (!res || res.exitCode !== 0) return null;
+  return String(res.stdout || "").split("\n").filter(Boolean)
+    .map((l) => l.split("\t")).filter(([a]) => a !== "-")
+    .reduce((sum, [a]) => sum + Number(a || 0), 0);
+}
+
+export async function runGoldenTask(task, opts = {}) {
+  const run = opts.run || defaultRun;
+  const fsApi = opts.fs || fs;
+  const workDir = opts.workDir;
+  if (!workDir) throw new Error("runGoldenTask requires opts.workDir");
+
+  const baseSha = opts.baseSha || null;
+  const kjResult = await run("kj", ["run", task.prompt, "-y"], {
+    cwd: workDir,
+    timeout: (task.timeout_minutes || 30) * 60_000,
+  });
+
+  const summaryPath = opts.summaryPath || await findLatestSummary(workDir);
+  if (!summaryPath) {
+    return { ok: false, kjExit: kjResult?.exitCode ?? -1, failures: [{
+      kind: "no_summary", expected: "summary.md", actual: null,
+      message: "kj run finished without producing a summary.md",
+    }] };
+  }
+  const content = await fsApi.readFile(summaryPath, "utf8");
+  const parsed = parseSummary(content);
+  const summaryAssertion = assertFromSummary(task, parsed);
+
+  const failures = [...summaryAssertion.failures];
+
+  if (Array.isArray(task.expected_test_files) && task.expected_test_files.length > 0) {
+    const missing = await findMissingTestFiles(workDir, task.expected_test_files);
+    if (missing.length > 0) {
+      failures.push({ kind: "test_files_missing", expected: task.expected_test_files, actual: missing,
+        message: `expected test files not produced: ${missing.join(", ")}` });
+    }
+  }
+
+  if (baseSha) {
+    const loc = await totalLocSince(workDir, baseSha, run);
+    const [min, max] = task.allowed_loc_range;
+    if (loc !== null && (loc < min || loc > max)) {
+      failures.push({ kind: "loc_out_of_range", expected: `${min}..${max}`, actual: loc,
+        message: `LOC added (${loc}) is outside the allowed range [${min}, ${max}]` });
+    }
+  }
+
+  return {
+    ok: failures.length === 0,
+    kjExit: kjResult?.exitCode ?? null,
+    summaryPath,
+    parsed,
+    failures,
+  };
+}

package/src/golden/schema.js

@@ -0,0 +1,41 @@
+/**
+ * Golden tasks regression suite — schema (KJC-TSK-0374). Pure data,
+ * no I/O. See docs/golden-tasks.md (PR-3) for the full spec.
+ */
+
+import * as v from "valibot";
+
+const NonEmptyString = v.pipe(v.string(), v.minLength(1));
+const Percent = v.pipe(v.number(), v.minValue(0), v.maxValue(100));
+
+const NonNegInt = v.pipe(v.number(), v.integer(), v.minValue(0));
+const LocRangeSchema = v.pipe(v.array(NonNegInt), v.length(2),
+  v.check((arr) => arr[0] <= arr[1], "allowed_loc_range: min must be <= max"));
+
+export const GoldenTaskSchema = v.looseObject({
+  id: v.pipe(NonEmptyString, v.regex(/^[a-z0-9_-]+$/, "id must be lowercase a-z0-9_-")),
+  title: NonEmptyString,
+  prompt: NonEmptyString,
+  description: v.optional(v.string()),
+  timeout_minutes: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1)), 30),
+  expected_commits_min: NonNegInt,
+  expected_audit_status: v.picklist(["pass", "warning", "fail"]),
+  expected_test_files: v.array(NonEmptyString),
+  allowed_loc_range: LocRangeSchema,
+  expected_plan_adherence_min: v.optional(Percent),
+});
+
+/** @typedef {import("valibot").InferOutput<typeof GoldenTaskSchema>} GoldenTask */
+
+export function parseGoldenTask(raw) {
+  return v.parse(GoldenTaskSchema, raw);
+}
+
+export function safeParseGoldenTask(raw) {
+  const result = v.safeParse(GoldenTaskSchema, raw);
+  if (result.success) return { ok: true, task: result.output };
+  return { ok: false, issues: result.issues.map((iss) => ({
+    path: (iss.path || []).map((p) => p.key).join("."),
+    message: iss.message,
+  })) };
+}

package/src/orchestrator/config-init.js

@@ -5,6 +5,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { computeBaseRef, setSnapshot } from "../review/diff-generator.js";
+import { revParse } from "../utils/git.js";
 import { buildCoderPrompt } from "../prompts/coder.js";
 import { buildReviewerPrompt } from "../prompts/reviewer.js";
 import { resolveRole } from "../config.js";
@@ -367,12 +368,28 @@ export async function initializeSession({ task, config, flags, pgTaskId, pgProje
   const projectDir = config.projectDir || process.cwd();
   const project_id = projectSlug(projectDir);
 
+  // Capture HEAD at the very start of the run, separately from base_ref.
+  // session_start_sha was being conflated with base_ref (used for `git diff`)
+  // — when the user's repo had a single commit and no remote main, base_ref
+  // fell through to git's empty-tree SHA. The post-loop journal then read
+  // session_start_sha to enumerate "commits made by this run" and got back
+  // the entire history, including pre-existing commits. Capturing actual
+  // HEAD here makes "what did the run produce?" deterministic and correct.
+  // Falls back to baseRef when HEAD doesn't exist (zero-commits repo); in
+  // that case "everything since baseRef" still equals "everything the run
+  // produced" because there was no prior history.
+  let headAtStart;
+  try {
+    headAtStart = (await revParse("HEAD")) || baseRef;
+  } catch { headAtStart = baseRef; }
+
   const sessionInit = {
     task,
     project_id,
     config_snapshot: config,
     base_ref: baseRef,
     session_start_sha: baseRef,
+    head_at_start: headAtStart,
     last_reviewer_feedback: null,
     repeated_issue_count: 0,
     sonar_retry_count: 0,

package/src/orchestrator/drivers/post-loop.js

@@ -23,6 +23,9 @@
 
 import { generateDiff } from "../../review/diff-generator.js";
 import { finalizeGitAutomation } from "../../git/automation.js";
+import { listCommitsBetween, listFilesChangedSince } from "../../utils/git.js";
+import { loadPlan, projectSlug as slugFor } from "../../plan/plan-store.js";
+import { computePlanAdherenceScore } from "../../audit/plan-adherence.js";
 import { saveSession, markSessionStatus } from "../../session/store.js";
 import {
   setReviewerFeedback, setBudget, setRtkSavings, resetRetryCount,
@@ -151,6 +154,50 @@ export async function finalizeApprovedSession({ config, gitCtx, task, logger, se
       const { writeSummaryJournal: writeSummaryJournalV2 } =
         await import("../../session/journal/summary-writer.js");
       const startedAt = session._startedAt ? new Date(session._startedAt).toISOString() : undefined;
+      // 2026-05-07 dogfooding: gitResult.commits only carries the post-loop
+      // commit (scaffold), not the coder's own commit. The summary's
+      // "Commits" section was therefore misleading — it claimed the run
+      // produced one chore commit when in fact the coder had also written
+      // a docs/feat commit. Compute the full range from session_start_sha
+      // so every commit between then and HEAD shows up in execution order.
+      // try/catch (instead of `.catch(...)`) so we tolerate both promise
+      // rejection AND a sync return of undefined — the latter happens
+      // when a test mocks listCommitsBetween with a plain vi.fn() that
+      // resetAllMocks has stripped of its mockResolvedValue.
+      let allCommits = [];
+      try { allCommits = (await listCommitsBetween(session.head_at_start || session.session_start_sha)) || []; }
+      catch { allCommits = gitResult?.commits || []; }
+      const summaryCommits = allCommits.length > 0 ? allCommits : (gitResult?.commits || []);
+
+      // KJC-TSK-0376 — plan adherence metric (deepeval-inspired). When the
+      // run executed against a known plan (`kj run --plan <id>`), score how
+      // faithfully the coder followed it. Pure offline; safe-by-default
+      // (try/catch swallows missing helper or unreadable plan).
+      let planAdherence = null;
+      try {
+        const planId = session._planRef?.planId
+          || stageResults?.huReviewer?.planId
+          || null;
+        if (planId) {
+          const projectDir = config?.projectDir
+            || session.config_snapshot?.projectDir
+            || process.cwd();
+          const plan = await loadPlan(projectDir, planId).catch(() => null);
+          if (plan && Array.isArray(plan.hus) && plan.hus.length > 0) {
+            const filesChanged = await listFilesChangedSince(
+              session.head_at_start || session.session_start_sha,
+            ).catch(() => []);
+            planAdherence = computePlanAdherenceScore({
+              commits: summaryCommits,
+              plan,
+              filesChanged,
+            });
+          }
+        }
+      } catch (err) {
+        logger?.warn?.(`Plan adherence calculation skipped: ${err.message}`);
+      }
+
       await writeSummaryJournalV2(journalDir, {
         task: session.task,
         result: "APPROVED",
@@ -159,7 +206,7 @@ export async function finalizeApprovedSession({ config, gitCtx, task, logger, se
         durationMs: Date.now() - (session._startedAt || Date.now()),
         budget: budgetSummary(),
         stages: stageResults,
-        commits: gitResult?.commits || [],
+        commits: summaryCommits,
         files: journalFiles,
         startedAt,
         finishedAt: new Date().toISOString(),
@@ -173,6 +220,7 @@ export async function finalizeApprovedSession({ config, gitCtx, task, logger, se
           installed: session.autoInstalledSkills,
           recommended: session.skillsRecommended,
         },
+        planAdherence,
       }, { logger });
       logger.info(`Session journal written to ${journalDir}`);
     } catch (err) {
@@ -180,7 +228,21 @@ export async function finalizeApprovedSession({ config, gitCtx, task, logger, se
     }
   }
 
-  const endDetail = { approved: true, iterations: i, stages: stageResults, git: gitResult, budget: budgetSummary(), deferredIssues };
+  // Mirror the same enriched commit list into the session:end event so the
+  // terminal `🏁 Result` banner (printSessionGit) shows every commit the
+  // run produced, not just the post-loop scaffold one. We compute again
+  // (cheap: one git log call) rather than threading a variable through
+  // because the journal block is wrapped in try/catch and may have set
+  // `summaryCommits` to a fallback we don't want for the event detail.
+  // try/catch tolerates both promise rejection and sync undefined returns
+  // (see the journal block above for the detailed rationale).
+  let eventCommits = null;
+  try { eventCommits = await listCommitsBetween(session.head_at_start || session.session_start_sha); }
+  catch { /* leave null — we'll use gitResult unchanged */ }
+  const gitForEvent = (Array.isArray(eventCommits) && eventCommits.length > 0)
+    ? { ...gitResult, commits: eventCommits }
+    : gitResult;
+  const endDetail = { approved: true, iterations: i, stages: stageResults, git: gitForEvent, budget: budgetSummary(), deferredIssues };
   if (rtkSavings) endDetail.rtk_savings = rtkSavings;
   emitProgress(
     emitter,
@@ -332,7 +394,6 @@ export async function tryAutoStartBoard(config, logger, emitter, eventBase) {
 
   try {
     const { startBoard, renderBoardBanner } = await import("../../commands/board.js");
-    const { projectSlug: slugFor } = await import("../../plan/plan-store.js");
     const boardPort = config.hu_board.port || 4000;
     // Scope the board URL to the current run's project (`/p/<slug>`) so
     // the user lands on a filtered view, not the global dashboard.

package/src/orchestrator/flow-runner.js

@@ -60,6 +60,45 @@ import { runSecurityStage, runFinalAuditStage } from "./post-loop-stages.js";
 // PG card "In Progress" logic moved to src/planning-game/pipeline-adapter.js → initPgAdapter()
 
 
+/**
+ * Boundary guard: make sure the session's terminal status reflects what
+ * actually happened, even if some inner exit path forgot to call
+ * `markSessionStatus`. KJC-BUG-0037 (N1 dogfooding 2026-05-07): runs
+ * that took the Brain "max_iterations approved" / "Solomon-after-error
+ * approved" / "Brain solomon-approved" exits returned `{approved:true}`
+ * upstream but left `session.status = "running"` on disk indefinitely.
+ * `kj status` then showed "Pipeline RUNNING" forever and the HU Board
+ * carried a perma-zombie.
+ *
+ * Maps the result shape to a terminal status:
+ *   approved → "approved"
+ *   paused   → "paused"
+ *   cancelled → "cancelled"
+ *   anything else → "failed"
+ *
+ * Idempotent: only writes when the current status is still "running"
+ * (or unset). If an inner path already sealed it correctly, this is a
+ * no-op.
+ *
+ * Safe-by-default: never throws. A failure here must not block the
+ * top-level result from being returned to the caller.
+ *
+ * @param {object} session
+ * @param {object} [result]
+ */
+export async function sealSessionStatusIfStillRunning(session, result) {
+  try {
+    if (!session) return;
+    const current = session.status;
+    if (current && current !== "running") return;
+    let target = "failed";
+    if (result?.approved === true) target = "approved";
+    else if (result?.paused === true) target = "paused";
+    else if (result?.cancelled === true) target = "cancelled";
+    await markSessionStatus(session, target);
+  } catch { /* non-blocking */ }
+}
+
 export async function runFlow(opts) {
   // TSK-0338: isolate per-run state (git/diff runner, projectDir, snapshot)
   // inside an AsyncLocalStorage scope. Two concurrent `runFlow` invocations
@@ -193,12 +232,14 @@ async function _runFlowInner({ task, config, logger, flags = {}, emitter = null,
     // policies + acceptance-tests gate + Sonar + tester translation.
     const huBatch = await runHuBatch({ ctx, task, askQuestion, emitter, logger });
     if (huBatch.handled) {
+      await sealSessionStatusIfStillRunning(ctx.session, huBatch.result);
       return huBatch.result;
     }
 
     // --- Standard single-task pipeline (1 HU or no HU reviewer) ---
     const result = await runIterationLoop(ctx, { task: ctx.plannedTask, askQuestion, emitter, logger });
     await writeHistoryRecord({ sessionId: ctx.session.id, task, result, logger });
+    await sealSessionStatusIfStillRunning(ctx.session, result);
     return result;
   } finally {
     // --- Cleanup auto-installed skills ---

package/src/orchestrator/stages/sonar-stage.js

@@ -11,6 +11,7 @@ import {
 import { emitProgress, makeEvent } from "../../utils/events.js";
 import { invokeSolomon } from "../solomon-escalation.js";
 import { sonarUp, isSonarReachable } from "../../sonar/manager.js";
+import { canResolveSonarProjectKey } from "../../sonar/project-key.js";
 import { addEntries } from "../feedback-queue.js";
 
 /**
@@ -222,6 +223,24 @@ export async function runSonarStage({ config, logger, emitter, eventBase, sessio
     logger.info("SonarQube is ready");
   }
 
+  // 2026-05-07 (N4 dogfooding): when the working tree has neither a git
+  // remote nor an explicit `sonarqube.project_key`, the scanner inside
+  // SonarRole would throw "Missing git remote.origin.url" — the Brain
+  // logs that as a sonar error, the iteration cap is reached, and the
+  // run finalises as "approved" by exhaustion fallback even though no
+  // sonar gate ever ran. KJC-TSK-0373 silenced this for the audit
+  // collector but the run loop hit it on the parallel code path.
+  // Skipping cleanly here means the gate reports "SKIPPED" once and
+  // the iteration loop progresses on the next stage.
+  if (!await canResolveSonarProjectKey(config)) {
+    logger.info("Sonar gate skipped: no git remote and no sonarqube.project_key configured");
+    emitProgress(emitter, makeEvent("sonar:end", { ...eventBase, stage: "sonar" }, {
+      status: "skip",
+      message: "Sonar skipped — no git remote and no sonarqube.project_key configured (run `git remote add origin …` or set `sonarqube.project_key` to enable)"
+    }));
+    return { action: "ok", stageResult: { gateStatus: "SKIPPED", reason: "no git remote and no sonarqube.project_key configured" } };
+  }
+
   const sonarRole = new SonarRole({ config, logger, emitter });
   await sonarRole.init({ iteration });
   const sonarStart = Date.now();

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

@@ -199,11 +199,50 @@ export function buildSummaryMarkdown(input) {
 
   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).