karajan-code 2.10.2 → 2.12.0

package/README.md

@@ -23,7 +23,11 @@
 
 ---
 
-> **v2.10.2 released** — Patch release. `kj init` wizard expanded from 9 prompts to a full setup: per-role provider selection (10 roles, "inherit / pick CLI / disable"), automatic SonarQube token generation via REST API (no more web UI walkthrough), git automation flags (`auto_commit/push/pr`) and HU Board security (bind host + port). +16 new tests. Safe upgrade from 2.10.1.
+> **v2.12.0 released** — Quality-measurement release. Two new features land together: every `kj run` against a known plan now scores how faithfully the coder followed it (deterministic 0–100 **plan adherence** metric, four weighted components, rendered in `summary.md`), and a small **golden-tasks** regression suite (`todo-rest-api`, `npm-package-cli`, `react-counter-component`) catches output-quality drops between Karajan versions before npm publish. Plus the shrink-budget CI gate now exempts human-facing docs from its 200-LOC ceiling while keeping AI-rule files (CLAUDE.md, AGENTS.md, role prompts) capped. 3 PRs for plan adherence (#645–#647), 4 for golden tasks (#648, #650–#652), 1 for the CI policy (#649). 4522/4522 tests passing. Safe upgrade from 2.11.0.
+>
+> **v2.11.0** — Dogfooding pass release. Two-day pass through a 10-level test plan surfaced and fixed a long tail of UX papercuts and three latent bugs that only show up on fresh `/tmp` repos: the `SonarStage` no longer loops on remoteless projects (was burning iterations until `max_iterations`-fallback-approval), the post-loop `commitAll` now tolerates the locale-specific "nothing to commit" race, the HU sub-pipeline branches off `master`/`HEAD` when the configured `main` doesn't exist, and `runFlow` now seals `session.status` at the boundary so `kj status` never shows zombi `running` runs again. Plus `hu-board` gains automatic ephemeral-project cleanup and an in-UI help modal for the five views. 14 PRs (#624–#637), 4452/4452 tests passing. Safe upgrade from 2.10.2.
+>
+> **v2.10.2** — Patch release. `kj init` wizard expanded from 9 prompts to a full setup: per-role provider selection (10 roles, "inherit / pick CLI / disable"), automatic SonarQube token generation via REST API (no more web UI walkthrough), git automation flags (`auto_commit/push/pr`) and HU Board security (bind host + port). +16 new tests. Safe upgrade from 2.10.1.
 >
 > **v2.10.1** — Patch release. One-line fix for a stdout contamination bug in `kj audit --agent-readiness --json` (the `[info]` banner was breaking downstream `jq` pipes), plus polish in the asciinema demo scripts. Safe upgrade from 2.10.0.
 >

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.10.2",
+  "version": "2.12.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/audit/plan-adherence.js

@@ -0,0 +1,222 @@
+/**
+ * Plan adherence metric — KJC-TSK-0376 (deepeval-inspired).
+ * Pure offline 0-100 score: how faithfully did the coder follow the plan?
+ * Components (weighted): commit_attribution 40%, acceptance_tests 30%,
+ * scope_discipline 20%, dependency_order 10%. Components return null
+ * when no data; aggregator redistributes the weight.
+ * See docs/plan-adherence.md (PR-C) for the full spec.
+ */
+
+const WEIGHTS = {
+  commit_attribution: 40,
+  acceptance_tests: 30,
+  scope_discipline: 20,
+  dependency_order: 10,
+};
+
+/**
+ * Build a regex that matches the HU id anywhere in a commit message
+ * (case-insensitive, word-boundary friendly). The `_` and `-` characters
+ * appear inside HU ids so we anchor on whole-token rather than \b.
+ */
+function huIdMatcher(huId) {
+  const escaped = String(huId).replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&");
+  return new RegExp(`(^|[^a-z0-9])${escaped}([^a-z0-9]|$)`, "i");
+}
+
+/**
+ * Slugify an HU title for branch-name / scope matching. Mirrors the
+ * `buildHuBranchName` slug rule (lowercase, non-alnum → "-").
+ */
+function slugify(text) {
+  return String(text || "")
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9]+/g, "-")
+    .replaceAll(/(^-+)|(-+$)/g, "");
+}
+
+/**
+ * Try to attribute a single commit to one of the plan's HUs.
+ *
+ * Order of evidence, strongest first:
+ *   1. The HU id appears in the commit message.
+ *   2. The HU id appears in the branch name where the commit lives
+ *      (commit.branch is supplied by listCommitsBetween's caller when
+ *      it knows the per-HU branches).
+ *   3. The HU title slug matches the commit message.
+ *
+ * Returns the matched huId, or null when none of the above fires.
+ */
+export function attributeCommitToHu(commit, hus) {
+  if (!commit || !Array.isArray(hus) || hus.length === 0) return null;
+  const msg = String(commit.message || "");
+  const branch = String(commit.branch || "");
+  for (const hu of hus) {
+    if (!hu?.id) continue;
+    const matcher = huIdMatcher(hu.id);
+    if (matcher.test(msg)) return hu.id;
+    if (branch && matcher.test(branch)) return hu.id;
+  }
+  // Fallback: title slug
+  for (const hu of hus) {
+    const slug = slugify(hu.title);
+    if (!slug || slug.length < 6) continue;
+    if (slugify(msg).includes(slug)) return hu.id;
+  }
+  return null;
+}
+
+/**
+ * Component 1: commit attribution. Returns null when the run produced
+ * no commits at all (avoids penalising analysis-only or doc-only runs).
+ */
+export function computeCommitAttribution(commits, plan) {
+  if (!Array.isArray(commits) || commits.length === 0) return null;
+  if (!plan?.hus || plan.hus.length === 0) return null;
+  let attributed = 0;
+  for (const commit of commits) {
+    if (attributeCommitToHu(commit, plan.hus)) attributed += 1;
+  }
+  return Math.round((attributed / commits.length) * 100);
+}
+
+/**
+ * Component 2: acceptance test coverage. Heuristic: each HU declares
+ * `acceptance_tests`. We check whether at least one commit from that
+ * HU's pool has a `test:`-prefixed message. Per-HU score (1 or 0),
+ * averaged across HUs that DO declare tests. Returns null when no HU
+ * declares acceptance tests.
+ */
+export function computeAcceptanceTestCoverage(commits, plan) {
+  if (!plan?.hus || plan.hus.length === 0) return null;
+  if (!Array.isArray(commits) || commits.length === 0) return null;
+  const husWithTests = plan.hus.filter(
+    (hu) => Array.isArray(hu?.acceptance_tests) && hu.acceptance_tests.length > 0,
+  );
+  if (husWithTests.length === 0) return null;
+
+  let covered = 0;
+  for (const hu of husWithTests) {
+    const huCommits = (commits || []).filter(
+      (c) => attributeCommitToHu(c, [hu]) === hu.id,
+    );
+    const hasTestCommit = huCommits.some((c) =>
+      /^test[:(]/i.test(String(c.message || "").trim()),
+    );
+    if (hasTestCommit) covered += 1;
+  }
+  return Math.round((covered / husWithTests.length) * 100);
+}
+
+/**
+ * Component 3: scope discipline. For each file changed by the run, we
+ * try to match it against at least one HU's id slug, title slug, or
+ * `scope` text. A file that matches no HU is flagged as out-of-scope.
+ * Returns null when the run changed no files.
+ */
+export function computeScopeDiscipline(filesChanged, plan) {
+  if (!Array.isArray(filesChanged) || filesChanged.length === 0) return null;
+  if (!plan?.hus || plan.hus.length === 0) return null;
+  const huKeywords = plan.hus.map((hu) => ({
+    id: hu.id,
+    matchers: [
+      slugify(hu.id),
+      slugify(hu.title),
+      // Pull alpha-rich words from `scope` text (length >= 4).
+      ...String(hu.scope || "")
+        .toLowerCase()
+        .split(/[^a-z]+/)
+        .filter((w) => w.length >= 4),
+    ].filter(Boolean),
+  }));
+  let inScope = 0;
+  for (const file of filesChanged) {
+    const slug = slugify(file);
+    const matched = huKeywords.some((hk) =>
+      hk.matchers.some((m) => slug.includes(m) || file.includes(m)),
+    );
+    if (matched) inScope += 1;
+  }
+  return Math.round((inScope / filesChanged.length) * 100);
+}
+
+/**
+ * Component 4: dependency order. For every `(parent, child)` edge
+ * declared via `child.blocked_by`, check that the EARLIEST commit
+ * attributed to `parent` is older than the EARLIEST commit attributed
+ * to `child`. Returns null when no dependency edges exist.
+ *
+ * `commits` are expected oldest-first (the shape `listCommitsBetween`
+ * returns). When that's not the case the score still makes sense — we
+ * just compare relative positions in the array.
+ */
+export function computeDependencyOrder(commits, plan) {
+  if (!plan?.hus || plan.hus.length === 0) return null;
+  const edges = [];
+  for (const hu of plan.hus) {
+    for (const parentId of hu.blocked_by || []) {
+      edges.push([parentId, hu.id]);
+    }
+  }
+  if (edges.length === 0) return null;
+  if (!Array.isArray(commits) || commits.length === 0) return null;
+
+  // Build huId → first commit index (oldest first attribution).
+  const firstIndex = new Map();
+  commits.forEach((commit, idx) => {
+    const huId = attributeCommitToHu(commit, plan.hus);
+    if (huId && !firstIndex.has(huId)) firstIndex.set(huId, idx);
+  });
+
+  let respected = 0;
+  let evaluable = 0;
+  for (const [parentId, childId] of edges) {
+    const p = firstIndex.get(parentId);
+    const c = firstIndex.get(childId);
+    if (p === undefined || c === undefined) continue; // can't evaluate
+    evaluable += 1;
+    if (p < c) respected += 1;
+  }
+  if (evaluable === 0) return null;
+  return Math.round((respected / evaluable) * 100);
+}
+
+/**
+ * Aggregator: compute every component and weight them. Components
+ * that return `null` are excluded and their weight redistributed
+ * proportionally across the rest, so a run that legitimately has no
+ * acceptance tests or no dependencies isn't penalised.
+ *
+ * Returns the full structured result (see file header for shape).
+ */
+export function computePlanAdherenceScore({ commits, plan, filesChanged }) {
+  const breakdown = {
+    commit_attribution: computeCommitAttribution(commits, plan),
+    acceptance_tests: computeAcceptanceTestCoverage(commits, plan),
+    scope_discipline: computeScopeDiscipline(filesChanged, plan),
+    dependency_order: computeDependencyOrder(commits, plan),
+  };
+
+  // Weighted average over non-null components only.
+  let totalWeight = 0;
+  let weightedSum = 0;
+  for (const [key, weight] of Object.entries(WEIGHTS)) {
+    const value = breakdown[key];
+    if (value === null || value === undefined) continue;
+    totalWeight += weight;
+    weightedSum += value * weight;
+  }
+  const score = totalWeight === 0 ? null : Math.round(weightedSum / totalWeight);
+
+  // Per-HU detail: was the HU "touched" (attributed at least one commit)?
+  const hu_scores = (plan?.hus || []).map((hu) => {
+    const huCommits = (commits || []).filter(
+      (c) => attributeCommitToHu(c, [hu]) === hu.id,
+    );
+    const issues = [];
+    if (huCommits.length === 0) issues.push("no commit attributed");
+    return { huId: hu.id, attributed: huCommits.length > 0, issues };
+  });
+
+  return { score, breakdown, hu_scores };
+}

package/src/audit/sonar-findings.js

@@ -22,6 +22,7 @@
 
 import { isSonarReachable } from "../sonar/manager.js";
 import { getOpenIssues, getQualityGateStatus } from "../sonar/api.js";
+import { canResolveSonarProjectKey } from "../sonar/project-key.js";
 
 /**
  * Collect deterministic Sonar findings for the audit prompt.
@@ -43,6 +44,17 @@ export async function collectSonarFindings(config, logger = null) {
     return { available: false, reason: `sonar host ${host} not reachable` };
   }
 
+  // No git remote and no explicit project_key → silent skip. This is the
+  // typical `kj run` in a fresh /tmp/... folder. Reporting it as a
+  // warning treats it like an error (which it isn't — sonar simply
+  // doesn't apply to a remoteless repo).
+  if (!(await canResolveSonarProjectKey(config))) {
+    return {
+      available: false,
+      reason: "not applicable: no git remote and no sonarqube.project_key configured",
+    };
+  }
+
   let issuesResult;
   try {
     issuesResult = await getOpenIssues(config);

package/src/cli/register-meta.js

@@ -24,7 +24,7 @@ export function registerMeta(program, { pkgVersion }) {
   program
     .command("discover")
     .description("Analyze task for gaps, ambiguities and missing info")
-    .argument("[task]", "Task description (or use --task-file)")
+    .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md)")
     .option("--mode <name>", "Discovery mode: gaps|momtest|wendel|classify|jtbd", "gaps")
     .option("--discover <name>", "Override discover agent")
@@ -41,7 +41,7 @@ export function registerMeta(program, { pkgVersion }) {
   program
     .command("triage")
     .description("Classify task complexity and recommend pipeline roles")
-    .argument("[task]", "Task description (or use --task-file)")
+    .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md)")
     .option("--triage <name>", "Override triage agent")
     .option("--triage-model <name>", "Override triage model")
@@ -57,7 +57,7 @@ export function registerMeta(program, { pkgVersion }) {
   program
     .command("researcher")
     .description("Research codebase for a task (files, patterns, constraints)")
-    .argument("[task]", "Task description (or use --task-file)")
+    .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md)")
     .option("--researcher <name>", "Override researcher agent")
     .option("--researcher-model <name>", "Override researcher model")
@@ -72,7 +72,7 @@ export function registerMeta(program, { pkgVersion }) {
   program
     .command("architect")
     .description("Design solution architecture (layers, patterns, contracts)")
-    .argument("[task]", "Task description (or use --task-file)")
+    .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md)")
     .option("--architect <name>", "Override architect agent")
     .option("--architect-model <name>", "Override architect model")

package/src/cli/register-pipeline.js

@@ -40,7 +40,7 @@ export function registerPipeline(program, { pkgVersion }) {
   program
     .command("run")
     .description("Run coder+sonar+reviewer loop")
-    .argument("[task]", "Task description (or use --task-file to read from a .md file)")
+    .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md). Alternative to the positional task argument.")
     .option("-y, --yes", "Skip the cwd confirmation prompt (CI / scripted runs).")
     .option("--planner <name>")
@@ -135,7 +135,7 @@ export function registerPipeline(program, { pkgVersion }) {
   program
     .command("code")
     .description("Run only coder")
-    .argument("[task]", "Task description (or use --task-file)")
+    .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md)")
     .option("--coder <name>")
     .option("--coder-model <name>")
@@ -150,7 +150,7 @@ export function registerPipeline(program, { pkgVersion }) {
   program
     .command("review")
     .description("Run only reviewer")
-    .argument("[task]", "Task description (or use --task-file)")
+    .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md)")
     .option("--reviewer <name>")
     .option("--reviewer-model <name>")

package/src/cli/register-plan.js

@@ -26,7 +26,7 @@ export function registerPlan(program, { pkgVersion }) {
   plan
     .command("generate", { isDefault: true })
     .description("Generate implementation plan with HUs")
-    .argument("[task]", "Task description (or use --task-file)")
+    .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md)")
     .option("--planner <name>")
     .option("--planner-model <name>")

package/src/commands/board.js

@@ -126,14 +126,29 @@ export async function startBoard(desiredPort = 4000, opts = {}) {
   const karajanHome = getKarajanHome();
   fs.mkdirSync(karajanHome, { recursive: true });
 
+  // Open a log file for the daemon. Pre-fix the daemon was spawned
+  // with `stdio: "ignore"`, so every `console.log` from server.js
+  // (including the new [zombie-reaper] messages) went straight to
+  // /dev/null and the user had no way to see what was happening.
+  // The file is opened in append-only mode so successive starts
+  // don't truncate the history.
+  const logPath = path.join(karajanHome, "hu-board.log");
+  const logFd = fs.openSync(logPath, "a");
+  fs.writeSync(
+    logFd,
+    `\n--- kj board start at ${new Date().toISOString()} (port ${port}, bind ${bind}) ---\n`,
+  );
+
   // Use process.execPath (absolute path to current node binary) instead of "node".
   // Fixes ENOENT on nvm setups where `node` is not in the spawned process's PATH.
   const child = spawn(process.execPath, [serverPath], {
     env: { ...process.env, PORT: String(port), BIND_HOST: bind },
     detached: true,
-    stdio: "ignore",
+    stdio: ["ignore", logFd, logFd],
     cwd: BOARD_DIR
   });
+  // The parent doesn't need the fd anymore — the child inherited it.
+  fs.closeSync(logFd);
   // Swallow spawn errors so an HU Board failure never crashes the pipeline.
   child.on("error", () => { /* non-blocking — caller logs via tryAutoStartBoard catch */ });
   if (!child.pid) {
@@ -143,10 +158,16 @@ export async function startBoard(desiredPort = 4000, opts = {}) {
   // Detach for real: `detached: true` only sets up the new session;
   // without `unref()` the parent's event loop still holds a reference
   // to the child handle and `kj board start` hangs at the prompt
-  // instead of returning. Pair this with stdio:"ignore" (already set)
-  // to ensure the parent isn't waiting on any of the child's pipes.
+  // instead of returning.
   child.unref();
-  return { ok: true, alreadyRunning: false, pid: child.pid, url: buildBoardUrl(port, projectSlug), port };
+  return {
+    ok: true,
+    alreadyRunning: false,
+    pid: child.pid,
+    url: buildBoardUrl(port, projectSlug),
+    port,
+    logPath,
+  };
 }
 
 export async function stopBoard(opts = {}) {
@@ -273,6 +294,9 @@ export async function boardCommand({ action = "start", port = 4000, bind = "127.
         logger.info(`HU Board already running (PID ${result.pid}) at ${result.url}`);
       } else {
         logger.info(`HU Board started (PID ${result.pid}) at ${result.url}`);
+        if (result.logPath) {
+          logger.info(`Daemon logs: tail -f ${result.logPath}`);
+        }
         if (bind !== "127.0.0.1" && bind !== "localhost") {
           logger.warn(`HU Board bound to ${bind} — token auth enforced for non-loopback peers. Token: ~/.karajan/hu-board/token`);
         }

package/src/commands/init.js

@@ -277,6 +277,22 @@ async function runWizard(config, logger) {
   return config;
 }
 
+/**
+ * Backwards-compatible alias for `writeConfig`. Pre-KJC-BUG-0036 this
+ * wrapper was the *only* writer that stripped `sonarqube.enabled`
+ * before serialising — we needed it because the global `writeConfig`
+ * would happily persist the wizard's transient hint. KJC-BUG-0036
+ * moved that strip (and the equivalent `_deprecated` strip) into
+ * `writeConfig` itself, so this is now a thin alias kept around to
+ * keep callers and tests stable. Prefer `writeConfig` in new code.
+ *
+ * @param {string} configPath
+ * @param {object} config
+ */
+export async function writeInitConfig(configPath, config) {
+  await writeConfig(configPath, config);
+}
+
 async function handleConfigSetup({ config, configExists, interactive, configPath, logger }) {
   if (configExists && interactive) {
     const wizard = createWizard();
@@ -284,7 +300,7 @@ async function handleConfigSetup({ config, configExists, interactive, configPath
       const reconfigure = await wizard.confirm("Config already exists. Reconfigure?", false);
       if (reconfigure) {
         const updated = await runWizard(config, logger);
-        await writeConfig(configPath, updated);
+        await writeInitConfig(configPath, updated);
         logger.info(`Updated ${configPath}`);
       } else {
         logger.info("Keeping existing config.");
@@ -294,10 +310,10 @@ async function handleConfigSetup({ config, configExists, interactive, configPath
     }
   } else if (!configExists && interactive) {
     const updated = await runWizard(config, logger);
-    await writeConfig(configPath, updated);
+    await writeInitConfig(configPath, updated);
     logger.info(`Created ${configPath}`);
   } else if (!configExists) {
-    await writeConfig(configPath, config);
+    await writeInitConfig(configPath, config);
     logger.info(`Created ${configPath}`);
   }
 }
@@ -561,7 +577,7 @@ export async function initCommand({ logger, flags = {} }) {
       config.development.methodology = config.development.methodology || "tdd";
     }
 
-    await writeConfig(configPath, config);
+    await writeInitConfig(configPath, config);
   } else {
     logger.info("No project stack detected — using default configuration.");
   }
@@ -582,7 +598,10 @@ export async function initCommand({ logger, flags = {} }) {
   await scaffoldCiGateway(config, flags, logger);
 
   // Persist any changes setupSonarQube made (token, etc.) back to disk.
-  await writeConfig(configPath, config);
+  // Use writeInitConfig so the deprecated `sonarqube.enabled` key —
+  // which setupSonarQube still mutates as an in-memory hint — never
+  // reaches the YAML file.
+  await writeInitConfig(configPath, config);
 
   // Telemetry: anonymous install event (non-blocking)
   const { sendTelemetryEvent } = await import("../utils/telemetry.js");

package/src/config/loader.js

@@ -128,9 +128,40 @@ export async function loadConfig(projectDir) {
   return { config: merged, path: configPath, exists: globalExists, hasProjectConfig: !!projectConfig };
 }
 
+/**
+ * Runtime-only keys that the loader synthesises on every load (or that
+ * a wizard uses as transient in-memory hints). They MUST NOT survive
+ * to the on-disk YAML — otherwise the `kj run` deprecation warning
+ * fossilises (KJC-BUG-0036, observed in dogfooding 2026-05-07: the
+ * `_deprecated.sonarqubeEnabledKey: true` block ended up baked into
+ * `~/.karajan/kj.config.yml` and re-fired the warning on every run
+ * even after the user cleaned `sonarqube.enabled`).
+ *
+ * Pure: returns a shallow-copied config without the runtime keys —
+ * the caller's object is left untouched.
+ */
+function stripRuntimeOnlyKeys(config) {
+  if (!config || typeof config !== "object") return config;
+  const out = { ...config };
+  // _deprecated is loader-synthesised — never written intentionally.
+  if ("_deprecated" in out) delete out._deprecated;
+  // sonarqube.enabled was deprecated in v2.7.4. The init wizard still
+  // uses it as a hint to drive setupSonarQube during install, but the
+  // runtime ignores it. Persisting it would re-trigger the deprecation
+  // warning on every subsequent kj run.
+  if (out.sonarqube && typeof out.sonarqube === "object"
+      && Object.prototype.hasOwnProperty.call(out.sonarqube, "enabled")) {
+    const { enabled: _drop, ...rest } = out.sonarqube;
+    void _drop;
+    out.sonarqube = rest;
+  }
+  return out;
+}
+
 export async function writeConfig(configPath, config) {
   await ensureDir(path.dirname(configPath));
-  await fs.writeFile(configPath, yaml.dump(config, { lineWidth: 120 }), "utf8");
+  const sanitized = stripRuntimeOnlyKeys(config);
+  await fs.writeFile(configPath, yaml.dump(sanitized, { lineWidth: 120 }), "utf8");
 }
 
 // Declarative mappings for applyRunOverrides to reduce cognitive complexity.

package/src/git/automation.js

@@ -15,14 +15,88 @@ import {
   buildBranchName,
   commitAll,
   pushBranch,
-  createPullRequest
+  createPullRequest,
+  listPendingPaths
 } from "../utils/git.js";
 
-export function commitMessageFromTask(task) {
+/**
+ * Karajan writes / updates several internal directories during a pipeline
+ * run (the workspace scaffold + the session journal). When they're the
+ * ONLY thing pending at finalization, the post-loop commit shouldn't
+ * inherit the user task's `feat:` message — it should be a clear
+ * `chore: scaffold karajan workspace` so `git log --oneline` reads:
+ *
+ *     2d770aa  docs: add JSDoc comment to index.js
+ *     abc1234  chore: scaffold karajan workspace
+ *     8a95ef0  initial
+ *
+ * A path counts as scaffolding when it lives at one of these prefixes
+ * OR is the project's root `.gitignore` (we extend it to include
+ * stack-specific entries during triage).
+ */
+const KARAJAN_SCAFFOLD_PREFIXES = [
+  ".karajan/",
+  ".reviews/",
+  ".kj/",
+  ".agent/",
+];
+
+function isKarajanScaffoldPath(p) {
+  if (p === ".gitignore") return true;
+  return KARAJAN_SCAFFOLD_PREFIXES.some((prefix) => p.startsWith(prefix));
+}
+
+/**
+ * @param {string[]} paths
+ * @returns {boolean} true when every pending path is a Karajan internal
+ */
+export function pendingPathsAreOnlyKarajanScaffold(paths) {
+  if (!Array.isArray(paths) || paths.length === 0) return false;
+  return paths.every(isKarajanScaffoldPath);
+}
+
+/**
+ * Map the taskType (as classified by triage) to the matching
+ * Conventional Commits prefix. When triage hasn't run or the type is
+ * unknown we default to `feat:` (the pre-fix behaviour).
+ */
+const TASK_TYPE_TO_PREFIX = {
+  doc: "docs",
+  "add-tests": "test",
+  refactor: "refactor",
+  infra: "chore",
+  sw: "feat",
+};
+
+function prefixForTaskType(taskType) {
+  return TASK_TYPE_TO_PREFIX[taskType] || "feat";
+}
+
+export function commitMessageFromTask(task, taskType = null) {
   const clean = String(task || "")
     .replaceAll(/\s+/g, " ")
     .trim();
-  return `feat: ${clean.slice(0, 72) || "karajan update"}`;
+  const prefix = prefixForTaskType(taskType);
+  return `${prefix}: ${clean.slice(0, 72) || "karajan update"}`;
+}
+
+/**
+ * Build the message used by `finalizeGitAutomation` for the post-loop
+ * commit. Two paths:
+ *   - When the only pending changes are Karajan scaffold files
+ *     (.gitignore, .karajan/, .reviews/, ...), use a fixed
+ *     `chore: scaffold karajan workspace` message. This avoids the
+ *     "duplicate feat:" git log seen when triage extends .gitignore
+ *     for a freshly detected stack and the coder already committed
+ *     the user-visible change.
+ *   - Otherwise, fall back to `commitMessageFromTask(task, taskType)`,
+ *     respecting the type for the prefix.
+ */
+export function buildFinalizeCommitMessage({ task, taskType, pendingPaths }) {
+  if (pendingPathsAreOnlyKarajanScaffold(pendingPaths)) {
+    return "chore: scaffold karajan workspace";
+  }
+  return commitMessageFromTask(task, taskType);
 }
 
 export async function prepareGitAutomation({ config, task, logger, session }) {
@@ -173,7 +247,23 @@ export async function incrementalPush({ gitCtx, task, logger, session }) {
 export async function finalizeGitAutomation({ config, gitCtx, task, logger, session, stageResults = null }) {
   if (!gitCtx?.enabled) return { git: "disabled", commits: [] };
 
-  const commitMsg = config.git.commit_message || commitMessageFromTask(task);
+  // Take a snapshot of pending paths BEFORE staging so we can decide
+  // whether what's about to be committed is just Karajan scaffolding
+  // (in which case we use `chore: scaffold karajan workspace`) or a
+  // real, user-visible change (in which case we honour the task's
+  // taskType for the Conventional Commits prefix).
+  const taskType = stageResults?.triage?.taskType ?? null;
+  let pendingPaths = [];
+  if (config.git.auto_commit) {
+    try {
+      pendingPaths = await listPendingPaths();
+    } catch { /* best-effort — fall back to default message */ }
+  }
+
+  const commitMsg =
+    config.git.commit_message
+    || buildFinalizeCommitMessage({ task, taskType, pendingPaths });
+
   let committed = false;
   const commits = [];
   if (config.git.auto_commit) {