karajan-code 4.70.4 → 5.0.0

package/src/domains/domain-synthesizer.js

@@ -1,129 +0,0 @@
-/**
- * Domain context synthesizer.
- * Filters relevant sections from domain files based on task + hints,
- * and compacts the output to stay within a token budget.
- */
-
-const DEFAULT_MAX_TOKENS = 4000;
-const CHARS_PER_TOKEN = 4;
-
-/**
- * Synthesize a domain context string from selected domains,
- * filtered by relevance to the task and domain hints.
- *
- * @param {Object} params
- * @param {string} params.task — task description
- * @param {string[]} params.domainHints — keywords from triage
- * @param {import('./domain-loader.js').DomainFile[]|null} params.selectedDomains
- * @param {number} [params.maxTokens=4000] — token budget (0 = unlimited)
- * @returns {string} synthesized markdown context or empty string
- */
-export function synthesizeDomainContext({ task, domainHints = [], selectedDomains, maxTokens = DEFAULT_MAX_TOKENS }) {
-  if (!selectedDomains?.length) return "";
-
-  const keywords = buildKeywords(task, domainHints);
-  const domainBlocks = [];
-
-  for (const domain of selectedDomains) {
-    const sections = domain.sections || [];
-    if (!sections.length) continue;
-
-    // Score all sections but include them all (domain was explicitly selected).
-    // Sort by relevance so highest-scoring sections survive token truncation.
-    const scored = sections
-      .map(section => ({
-        section,
-        score: scoreSection(section, keywords)
-      }))
-      .sort((a, b) => b.score - a.score);
-
-    const selected = scored.map(s => s.section);
-
-    const sectionMd = selected
-      .map(s => `#### ${s.heading}\n${s.content}`)
-      .join("\n\n");
-
-    domainBlocks.push(`### ${domain.name}\n\n${sectionMd}`);
-  }
-
-  if (!domainBlocks.length) return "";
-
-  let result = domainBlocks.join("\n\n---\n\n");
-
-  // Truncate by token budget if needed
-  if (maxTokens > 0) {
-    const maxChars = maxTokens * CHARS_PER_TOKEN;
-    if (result.length > maxChars) {
-      result = truncateBySection(result, maxChars);
-    }
-  }
-
-  return result;
-}
-
-/**
- * Build a set of lowercase keywords from task text and domain hints.
- * @param {string} task
- * @param {string[]} hints
- * @returns {string[]}
- */
-function buildKeywords(task, hints) {
-  const words = new Set();
-
-  // Add domain hints
-  for (const h of hints) {
-    words.add(h.toLowerCase());
-  }
-
-  // Extract meaningful words from task (>3 chars, skip stop words)
-  const stopWords = new Set(["the", "this", "that", "with", "from", "have", "will", "should", "could", "would", "been", "being", "their", "there", "where", "when", "what", "which", "about", "into", "some", "than", "then", "them", "they", "also", "each", "more", "most", "other"]);
-
-  const taskWords = task
-    .toLowerCase()
-    .replaceAll(/[^a-z0-9\s-]/g, " ")
-    .split(/\s+/)
-    .filter(w => w.length > 3 && !stopWords.has(w));
-
-  for (const w of taskWords) {
-    words.add(w);
-  }
-
-  return Array.from(words);
-}
-
-/**
- * Score a section by keyword overlap.
- * @param {import('./domain-loader.js').DomainSection} section
- * @param {string[]} keywords
- * @returns {number}
- */
-function scoreSection(section, keywords) {
-  const text = `${section.heading} ${section.content}`.toLowerCase();
-  let score = 0;
-  for (const kw of keywords) {
-    if (text.includes(kw)) score++;
-  }
-  return score;
-}
-
-/**
- * Truncate result by dropping trailing sections to fit within maxChars.
- * Preserves complete sections rather than cutting mid-sentence.
- * @param {string} text
- * @param {number} maxChars
- * @returns {string}
- */
-function truncateBySection(text, maxChars) {
-  // Split by section markers (#### or ###)
-  const parts = text.split(/(?=^#{3,4}\s)/m);
-  let result = "";
-
-  for (const part of parts) {
-    if (result.length + part.length > maxChars && result.length > 0) {
-      break;
-    }
-    result += part;
-  }
-
-  return result.trim();
-}

package/src/git/automation.js

@@ -1,433 +0,0 @@
-/**
- * Git automation helpers for the pipeline.
- * Extracted from orchestrator.js for testability and reuse.
- */
-
-import { addCheckpoint } from "../session/store.js";
-import { setGitPreexisting } from "../session/mutators.js";
-import { pipelineSonarBlock, stampStagedVerdict } from "../review/verdict-store.js";
-import { branchSize } from "../commands/pr-size.js";
-import { pushRemedy } from "./hu-automation.js";
-import { resolveRunIdentity } from "./run-identity.js";
-import { getRunContext } from "../utils/run-context.js";
-import {
-  ensureGitRepo,
-  currentBranch,
-  hasCommits,
-  fetchBase,
-  syncBaseBranch,
-  ensureBranchUpToDateWithBase,
-  createBranch,
-  checkoutBranch,
-  buildBranchName,
-  commitAll,
-  pushBranch,
-  createPullRequest,
-  listPendingPaths,
-  hasRemote
-} from "../utils/git.js";
-
-/**
- * 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) {
-  // KJC-BUG-0413 (#2565): the header comes from the first paragraph, without
-  // its leading Markdown marks; the whole task made "feat: # Roadmap ... Context: ...".
-  const firstParagraph = String(task || "").trim().split(/\n[ \t]*\r?\n/)[0];
-  const clean = firstParagraph
-    .replace(/^[#>*\-\s]+/, "")
-    .replaceAll(/\s+/g, " ")
-    .trim();
-  const prefix = prefixForTaskType(taskType);
-  // KJC-BUG-0294 (#1993): cut on a word, never mid-word (a title with no blank keeps the hard cut).
-  const cut = clean.length > 72 ? clean.slice(0, 72).replace(/\s+\S*$/, "") : clean;
-  return `${prefix}: ${cut || "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);
-}
-
-// KJC-BUG-0249 (#1896): a branch named after the card is the same on a second
-// run of that card, so one already there is taken, not recreated.
-async function checkoutRunBranch(created) {
-  try {
-    await createBranch(created);
-  } catch (err) {
-    if (!/already exists/i.test(err.message)) throw err;
-    await checkoutBranch(created);
-  }
-}
-
-export async function prepareGitAutomation({ config, task, logger, session, preexisting: resumedBaseline = null }) {
-  const enabled = config.git.auto_commit || config.git.auto_push || config.git.auto_pr;
-  if (!enabled) {
-    // KJC-TSK-1237: the format stage needs the baseline also when kj does not
-    // commit; outside git there is none, and that stage says so.
-    let baseline = resumedBaseline;
-    if (!baseline) {
-      try {
-        baseline = await listPendingPaths();
-      } catch {
-        baseline = null;
-      }
-    }
-    if (session && Array.isArray(baseline)) setGitPreexisting(session, baseline);
-    return { enabled: false };
-  }
-
-  if (!(await ensureGitRepo())) {
-    throw new Error("Git automation requested but current directory is not a git repository");
-  }
-
-  // KJC-BUG-0246 (#1893): one identity for every commit of the run, resolved
-  // once: the clone's declaration, else the repository's config, else the
-  // global one. From the global config it is said, because another session
-  // may switch it mid-run. Nothing resolvable: git refuses the commit loudly.
-  const identity = resolveRunIdentity({ projectDir: config.projectDir || process.cwd() });
-  const runContext = getRunContext();
-  if (identity && runContext) runContext.gitIdentity = identity;
-  if (identity) {
-    logger.info(`Git identity for this run: ${identity.name} <${identity.email}> (${identity.source})`);
-    if (identity.source === "global") logger.warn("The identity comes from the global git config, which another session may switch mid-run: declare this clone's with kj identity set, or set user.email in this repository");
-  } else {
-    logger.warn("No git identity resolvable (kj identity set, or git config user.name and user.email): the first commit will fail");
-  }
-
-  const baseBranch = config.base_branch;
-  const autoRebase = config.git.auto_rebase !== false;
-  // KJC-BUG-0294 (#1993): what is dirty or untracked NOW is not the run's; the
-  // pipeline commits only what it changes. Both names of a pending rename are
-  // kept. Fails closed: with no answer from git the run stops here rather than
-  // commit the person's pending changes later.
-  // KJC-BUG-0412 (#2564): a resumed run keeps the baseline of the session it
-  // resumes; the tree now also holds that session's own work.
-  const preexisting = resumedBaseline ?? await listPendingPaths();
-  if (session) setGitPreexisting(session, preexisting);
-  const repoHasCommits = await hasCommits();
-
-  // New repo without commits: create branch directly (no fetch/sync possible)
-  if (!repoHasCommits) {
-    const created = buildBranchName(config.git.branch_prefix || "feat/", task, session?.pg_task_id || null);
-    // git checkout -b works even without commits (creates orphan-like branch on first commit)
-    await createBranch(created);
-    logger.info(`New repo — created working branch: ${created}`);
-    await addCheckpoint(session, { stage: "git-prep", branch: created, created: true, newRepo: true });
-    return { enabled: true, branch: created, baseBranch, autoRebase, preexisting };
-  }
-
-  await fetchBase(baseBranch).catch(() => {
-    // No remote — skip fetch (new project without push)
-    logger.info("No remote configured — skipping fetch");
-  });
-
-  let branch;
-  try {
-    branch = await currentBranch();
-  } catch {
-    // HEAD exists but branch detection failed — unusual, treat as main
-    branch = baseBranch;
-  }
-
-  if (branch === baseBranch) {
-    await syncBaseBranch({ baseBranch, autoRebase }).catch(() => {
-      // No remote tracking — skip sync for new projects
-    });
-    const created = buildBranchName(config.git.branch_prefix || "feat/", task, session?.pg_task_id || null);
-    await checkoutRunBranch(created);
-    branch = created;
-    logger.info(`Created working branch: ${branch}`);
-    await addCheckpoint(session, { stage: "git-prep", branch, created: true });
-  } else {
-    await ensureBranchUpToDateWithBase({ branch, baseBranch, autoRebase }).catch(() => {
-      // No remote tracking — skip rebase for new projects
-      logger.info("No remote tracking — skipping rebase check");
-    });
-    await addCheckpoint(session, { stage: "git-prep", branch, created: false });
-  }
-
-  return { enabled: true, branch, baseBranch, autoRebase, preexisting };
-}
-
-export function buildPrBody({ task: _task, stageResults }) {
-  const sections = ["Created by Karajan Code."];
-
-  const approach = stageResults?.planner?.approach;
-  if (approach) {
-    sections.push("", "## Approach", approach);
-  }
-
-  const steps = stageResults?.planner?.steps;
-  if (steps?.length) {
-    sections.push("", "## Steps");
-    for (let i = 0; i < steps.length; i++) {
-      sections.push(`${i + 1}. ${steps[i]}`);
-    }
-  }
-
-  const triageSubtasks = stageResults?.triage?.subtasks;
-  const shouldDecompose = stageResults?.triage?.shouldDecompose;
-  const pendingSubtasks = shouldDecompose && triageSubtasks?.length > 1 ? triageSubtasks.slice(1) : [];
-  if (pendingSubtasks.length > 0) {
-    sections.push("", "## Pending subtasks", "This PR addresses part of a larger task. The following subtasks were identified but not included:");
-    for (const subtask of pendingSubtasks) {
-      sections.push(`- [ ] ${subtask}`);
-    }
-  }
-
-  return sections.join("\n");
-}
-
-/**
- * Create an early PR after the first coder iteration (Karajan CI flow).
- * Commits, pushes, and creates a PR before the reviewer runs.
- * Returns { prNumber, prUrl, commits } or null if nothing to commit.
- */
-export async function earlyPrCreation({ gitCtx, task, logger, session, stageResults = null }) {
-  if (!gitCtx?.enabled) return null;
-
-  const commitMsg = commitMessageFromTask(task);
-  const commitResult = await commitAll(commitMsg, null, { exclude: gitCtx.preexisting || [] });
-  if (!commitResult.committed) {
-    logger.info("earlyPrCreation: no changes to commit");
-    return null;
-  }
-
-  const commits = commitResult.commit ? [commitResult.commit] : [];
-  await addCheckpoint(session, { stage: "ci-commit", committed: true });
-
-  await pushBranch(gitCtx.branch);
-  await addCheckpoint(session, { stage: "ci-push", branch: gitCtx.branch });
-  logger.info(`Pushed branch for early PR: ${gitCtx.branch}`);
-
-  const body = buildPrBody({ task, stageResults });
-  const prUrl = await createPullRequest({
-    baseBranch: gitCtx.baseBranch,
-    branch: gitCtx.branch,
-    title: commitMessageFromTask(task),
-    body
-  });
-  await addCheckpoint(session, { stage: "ci-pr", branch: gitCtx.branch, pr: prUrl });
-  logger.info(`Early PR created: ${prUrl}`);
-
-  // Extract PR number from URL (e.g. https://github.com/owner/repo/pull/42)
-  const prNumber = Number.parseInt(prUrl.split("/").pop(), 10) || null;
-  return { prNumber, prUrl, commits };
-}
-
-/**
- * Incremental push after each coder iteration (Karajan CI flow).
- * Commits and pushes without creating a new PR.
- */
-export async function incrementalPush({ gitCtx, task, logger, session }) {
-  if (!gitCtx?.enabled) return null;
-
-  const commitMsg = commitMessageFromTask(task);
-  const commitResult = await commitAll(commitMsg, null, { exclude: gitCtx.preexisting || [] });
-  if (!commitResult.committed) {
-    logger.info("incrementalPush: no changes to commit");
-    return null;
-  }
-
-  const commits = commitResult.commit ? [commitResult.commit] : [];
-  await addCheckpoint(session, { stage: "ci-incremental-commit", committed: true });
-
-  await pushBranch(gitCtx.branch);
-  await addCheckpoint(session, { stage: "ci-incremental-push", branch: gitCtx.branch });
-  logger.info(`Incremental push: ${gitCtx.branch}`);
-
-  return { commits };
-}
-
-const DEFAULT_PR_SIZE_LIMIT = 200;
-
-export async function finalizeGitAutomation({ config, gitCtx, task, logger, session, stageResults = null, review = null, measureSize = branchSize }) {
-  if (!gitCtx?.enabled) return { git: "disabled", commits: [] };
-  // KJC-BUG-0297 (#1993): the pipeline commits only what a reviewer approved. An
-  // approval that reviewed nothing (reviewer disabled) stamps no verdict and
-  // commits nothing: the changes stay in the tree, and the log says why.
-  if (review && review.reviewed === false) {
-    logger.warn("No review, no commit: the reviewer was disabled, so the pipeline commits nothing; the changes stay in the tree for a review (kj review --staged)");
-    await addCheckpoint(session, { stage: "git-commit", committed: false, skipped: "unreviewed" });
-    return { committed: false, branch: gitCtx.branch, prUrl: null, pr: null, commits: [], unreviewed: true };
-  }
-
-  // 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 = [];
-  // KJC-BUG-0299 (#1993): the PR budget is applied BEFORE the commit, with the
-  // CI gate's own count (kj pr-size), over what this commit will contain. A
-  // step planned at 150 lines once committed 960. Where the branch cannot be
-  // measured (a fresh repo with no base yet) kj says so and goes on.
-  if (config.git.auto_commit) {
-    const limit = Number(config.git.pr_size_limit) > 0 ? Number(config.git.pr_size_limit) : DEFAULT_PR_SIZE_LIMIT;
-    let size = null;
-    try {
-      size = await measureSize({ projectDir: config.projectDir || process.cwd(), base: gitCtx.baseBranch, exclude: gitCtx.preexisting || [] });
-    } catch (err) {
-      logger.warn(`pr-size: the branch could not be measured (${err.message}); the budget is not checked for this commit`);
-    }
-    // KJC-BUG-0434: net, as the CI gate counts it.
-    if (size && size.net > limit) {
-      logger.warn(`pr-size: ${size.net} net line(s) against ${gitCtx.baseBranch}, over the budget of ${limit}: nothing committed. Split the step (several commits, several HUs); the changes stay in the tree`);
-      await addCheckpoint(session, { stage: "git-commit", committed: false, skipped: "over-budget", added: size.added, net: size.net, limit });
-      return { committed: false, branch: gitCtx.branch, prUrl: null, pr: null, commits: [], overBudget: { added: size.added, net: size.net, limit } };
-    }
-    // ENV-F1: this path only runs after the pipeline's reviewer approved,
-    // so stamp that verdict for the staged diff — the v4 pre-commit gate
-    // (when the repo opted in) accepts the pipeline's own commit.
-    const commitResult = await commitAll(commitMsg, null, {
-      exclude: gitCtx.preexisting || [],
-      beforeCommit: ({ paths } = {}) => stampStagedVerdict({
-        projectDir: config?.projectDir || process.cwd(),
-        paths,
-        reviewer: config?.reviewer || "pipeline-reviewer",
-        summary: `kj run session ${session?.id || ""}: reviewer approved`.trim(),
-        // KJC-TSK-0838: the sonar stage result travels with the stamp.
-        sonar: pipelineSonarBlock(stageResults?.sonar),
-      }),
-    });
-    committed = commitResult.committed;
-    if (commitResult.commit) {
-      commits.push(commitResult.commit);
-    }
-    // KJC-BUG-0294: what was pending before the run stays out of the commit and is named;
-    // if the run also touched one of those files, its edit is in the tree, not in the commit.
-    if (commitResult.leftOut?.length) {
-      logger.warn(`Left out of the commit, pending before the run (review and commit them yourself): ${commitResult.leftOut.join(", ")}`);
-    }
-    await addCheckpoint(session, { stage: "git-commit", committed, leftOut: commitResult.leftOut || [] });
-    logger.info(committed ? "Committed changes" : "No changes to commit");
-  }
-
-  // KJC-BUG-0112: without an `origin` remote (the quickstart scenario:
-  // fresh folder + git init) push/PR automation has nothing to talk to —
-  // fetchBase used to throw here and escalate to Solomon on EVERY
-  // iteration, burning the whole budget on an expected condition.
-  const remoteAvailable = (config.git.auto_push || config.git.auto_pr)
-    ? await hasRemote()
-    : false;
-  if ((config.git.auto_push || config.git.auto_pr) && !remoteAvailable) {
-    logger.info("No remote configured — skipping push/PR automation");
-    await addCheckpoint(session, { stage: "git-push", skipped: "no-remote" });
-  }
-
-  if (remoteAvailable && (config.git.auto_push || config.git.auto_pr)) {
-    await fetchBase(gitCtx.baseBranch);
-    await ensureBranchUpToDateWithBase({
-      branch: gitCtx.branch,
-      baseBranch: gitCtx.baseBranch,
-      autoRebase: gitCtx.autoRebase
-    });
-    await addCheckpoint(session, { stage: "git-rebase-check", branch: gitCtx.branch });
-  }
-
-  if (remoteAvailable && (config.git.auto_push || config.git.auto_pr)) {
-    // KJC-BUG-0248 (#1895): a refused push stops the run loudly, with its remedy.
-    try {
-      await pushBranch(gitCtx.branch);
-    } catch (err) {
-      throw new Error(`push of ${gitCtx.branch} failed: ${err.message}. ${pushRemedy(err.message, gitCtx.branch)}`, { cause: err });
-    }
-    await addCheckpoint(session, { stage: "git-push", branch: gitCtx.branch });
-    logger.info(`Pushed branch: ${gitCtx.branch}`);
-  }
-
-  let prUrl = session.ci_pr_url || null;
-  if (remoteAvailable && config.git.auto_pr && !prUrl) {
-    const body = buildPrBody({ task, stageResults });
-    prUrl = await createPullRequest({
-      baseBranch: gitCtx.baseBranch,
-      branch: gitCtx.branch,
-      title: commitMessageFromTask(task),
-      body
-    });
-    await addCheckpoint(session, { stage: "git-pr", branch: gitCtx.branch, pr: prUrl });
-    logger.info("Pull request created");
-  } else if (prUrl) {
-    logger.info(`PR already exists (CI flow): ${prUrl}`);
-  }
-
-  return { committed, branch: gitCtx.branch, prUrl, pr: prUrl, commits };
-}

package/src/git/coder-commit-guard.js

@@ -1,40 +0,0 @@
-/**
- * KJC-BUG-0285 (#1982): the coder commits nothing; the pipeline does, once the
- * review approves. With --auto-commit the coder ran git commit inside its
- * iteration, before the reviewer, and the rejected commit stayed on the branch.
- * The stage reads HEAD before the coder runs and, when HEAD moved on top of it,
- * undoes those commits SOFTLY: the changes stay in the tree and the index for
- * the review. A rewritten branch (HEAD no longer descends from the start) is
- * left alone. Plain git, no injected runner: it never throws, it says.
- */
-import { spawnSync } from "node:child_process";
-
-const git = (args, cwd) => spawnSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
-
-/** @returns {string|null} the sha HEAD points at, or null outside a repo with commits */
-export function headSha(cwd = process.cwd()) {
-  try {
-    const res = git(["rev-parse", "HEAD"], cwd);
-    return res.status === 0 ? res.stdout.trim() : null;
-  } catch {
-    return null;
-  }
-}
-
-/** @returns {{undone: number, reason?: string}} */
-export function undoCommitsSince(sha, cwd = process.cwd()) {
-  if (!sha) return { undone: 0, reason: "no starting commit" };
-  try {
-    const head = headSha(cwd);
-    if (!head || head === sha) return { undone: 0 };
-    if (git(["merge-base", "--is-ancestor", sha, "HEAD"], cwd).status !== 0) {
-      return { undone: 0, reason: "HEAD no longer descends from the iteration's start" };
-    }
-    const undone = Number(git(["rev-list", "--count", `${sha}..HEAD`], cwd).stdout.trim());
-    const reset = git(["reset", "--soft", sha], cwd);
-    if (reset.status !== 0) return { undone: 0, reason: `git reset --soft failed: ${reset.stderr.trim()}` };
-    return { undone };
-  } catch (err) {
-    return { undone: 0, reason: err.message };
-  }
-}