karajan-code 4.70.4 → 5.0.0

package/src/prompts/hu-reviewer.js

@@ -1,244 +0,0 @@
-import { extractFirstJson } from "../utils/json-extract.js";
-import { getLanguageInstruction } from "../utils/locale.js";
-import { section, buildPromptLayout, joinLayout, STABLE, VOLATILE } from "./prompt-layout.js";
-
-const SUBAGENT_PREAMBLE = [
-  "IMPORTANT: You are running as a Karajan sub-agent.",
-  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
-  "Do NOT use any MCP tools. Focus only on evaluating HUs."
-].join(" ");
-
-const VALID_VERDICTS = new Set(["certified", "needs_rewrite", "needs_context"]);
-const VALID_ANTIPATTERNS = new Set([
-  "ghost_user", "swiss_army_knife", "implementation_leak",
-  "moving_goalpost", "orphan_story", "invisible_dependency", "premature_optimization"
-]);
-const DIMENSION_KEYS = [
-  "D1_jtbd_context", "D2_user_specificity", "D3_behavior_change",
-  "D4_control_zone", "D5_time_constraints", "D6_survivable_experiment"
-];
-
-/**
- * Build the prompt for the HU reviewer agent.
- * @param {{stories: Array<{id: string, text: string}>, instructions: string|null, context?: string|null}} params
- * @returns {string} The assembled prompt.
- */
-/**
- * Build the HU-reviewer prompt as a { stable, volatile } layout (Φ1,
- * KJC-PCS-0057): preamble, instructions, JSON schema and contexts are
- * identical across batches on the same project; the stories under
- * evaluation and the per-batch additional context go last.
- */
-function buildHuReviewerPromptLayout({ stories, instructions, context = null, productContext = null, domainContext = null, hu_language = "en" }) {
-  const langInstruction = getLanguageInstruction(hu_language);
-
-  return buildPromptLayout([
-    section(SUBAGENT_PREAMBLE, STABLE),
-    section(langInstruction, STABLE),
-    section(instructions, STABLE),
-    section("Return a single valid JSON object and nothing else.", STABLE),
-    section(`JSON schema: {"evaluations":[{"story_id":string,"scores":{"D1_jtbd_context":number,"D2_user_specificity":number,"D3_behavior_change":number,"D4_control_zone":number,"D5_time_constraints":number,"D6_survivable_experiment":number},"total":number,"antipatterns_detected":[string],"verdict":"certified|needs_rewrite|needs_context","evaluation_notes":string,"rewritten":object|null,"certified_hu":object|null,"context_needed":object|null}],"batch_summary":{"total":number,"certified":number,"needs_rewrite":number,"needs_context":number,"consolidated_questions":string}}`, STABLE),
-    section(productContext ? `## Product Context\n${productContext}` : null, STABLE),
-    section(domainContext ? `## Domain Context\n${domainContext}` : null, STABLE),
-    section("## Stories to Evaluate", VOLATILE),
-    ...stories.map((story) => section(`### ${story.id}\n${story.text}`, VOLATILE)),
-    section(context ? `## Additional Context\n${context}` : null, VOLATILE),
-  ]);
-}
-
-export function buildHuReviewerPrompt(options) {
-  return joinLayout(buildHuReviewerPromptLayout(options));
-}
-
-/**
- * Clamp a score to 0-10 range.
- * @param {*} value
- * @returns {number}
- */
-function clampScore(value) {
-  const n = Number(value);
-  if (!Number.isFinite(n)) return 0;
-  return Math.max(0, Math.min(10, Math.round(n)));
-}
-
-/**
- * Parse and validate a single evaluation object.
- * @param {object} raw
- * @returns {object|null}
- */
-function parseEvaluation(raw) {
-  if (!raw || !raw.story_id || !raw.scores) return null;
-
-  const scores = {};
-  for (const key of DIMENSION_KEYS) {
-    scores[key] = clampScore(raw.scores[key]);
-  }
-
-  const total = Object.values(scores).reduce((sum, v) => sum + v, 0);
-  const antipatterns = (Array.isArray(raw.antipatterns_detected) ? raw.antipatterns_detected : [])
-    .filter(ap => VALID_ANTIPATTERNS.has(ap));
-
-  const rawVerdict = String(raw.verdict || "").toLowerCase();
-  const verdict = VALID_VERDICTS.has(rawVerdict) ? rawVerdict : "needs_context";
-
-  return {
-    story_id: raw.story_id,
-    scores,
-    total,
-    antipatterns_detected: antipatterns,
-    verdict,
-    evaluation_notes: raw.evaluation_notes || "",
-    rewritten: raw.rewritten || null,
-    certified_hu: raw.certified_hu || null,
-    context_needed: raw.context_needed || null
-  };
-}
-
-const AC_PREFIX_RE = /^\[(GHERKIN|CHECKLIST|PRE_POST|INVARIANT)]\s*/i;
-
-/**
- * Detect the format of a single acceptance criterion.
- * Supports both prefixed strings ("[GHERKIN] Given...") and legacy Gherkin objects ({given, when, then}).
- * @param {string|object} criterion
- * @returns {{format: string, text: string}}
- */
-export function detectAcFormat(criterion) {
-  if (typeof criterion === "object" && criterion !== null && ("given" in criterion || "when" in criterion || "then" in criterion)) {
-    const text = `Given ${criterion.given || "..."}, When ${criterion.when || "..."}, Then ${criterion.then || "..."}`;
-    return { format: "gherkin", text };
-  }
-  if (typeof criterion === "string") {
-    const match = AC_PREFIX_RE.exec(criterion);
-    if (match) {
-      const format = match[1].toLowerCase();
-      const text = criterion.slice(match[0].length);
-      return { format, text };
-    }
-    return { format: "checklist", text: criterion };
-  }
-  return { format: "checklist", text: String(criterion) };
-}
-
-/**
- * Normalize an acceptance_criteria array to a uniform structure.
- * Handles both legacy Gherkin objects and prefixed strings.
- * @param {Array} criteria
- * @returns {Array<{format: string, text: string}>}
- */
-export function normalizeAcceptanceCriteria(criteria) {
-  if (!Array.isArray(criteria)) return [];
-  return criteria.map(detectAcFormat);
-}
-
-/**
- * Build a prompt that asks the AI to decompose a complex task into 2-5 formal HUs.
- * Each HU follows the role/goal/benefit format with acceptance criteria and optional dependencies.
- * @param {string} task - The complex task description to decompose.
- * @returns {string} The assembled decomposition prompt.
- */
-export function buildDecompositionPrompt(task, { criteria = [] } = {}) {
-  const sections = [SUBAGENT_PREAMBLE];
-
-  sections.push("## Task Decomposition");
-  sections.push(
-    "You are a senior product owner. Decompose the following complex task into 2-5 independent, implementable user stories (HUs).",
-    "Each HU must be small enough to implement in a single iteration and must follow the role/goal/benefit format."
-  );
-
-  sections.push(`## Task to Decompose\n${task}`);
-
-  // KJC-TSK-0989 (#1894): the card's criteria are the contract; each one must
-  // land in an HU, by number, or the run implements stories of its own invention.
-  if (criteria.length > 0) {
-    const numbered = criteria.map((c, i) => `${i + 1}. ${c}`).join("\n");
-    sections.push(`## Acceptance criteria of the card (the contract)\n${numbered}`);
-  }
-
-  sections.push(
-    "Return a single valid JSON object and nothing else.",
-    `JSON schema: {"stories":[{"id":string,"title":string,"role":string,"goal":string,"benefit":string,"acceptanceCriteria":[string],"dependsOn":[string],"covers":[number],"tier":"trivial"|"standard"|"deep","tierReason":string}]}`,
-    "Rules:",
-    "- Generate between 2 and 5 HUs",
-    "- Each id must be unique, formatted as HU-DECOMP-NNN (e.g. HU-DECOMP-001)",
-    "- dependsOn is an array of other HU ids from this decomposition that must be completed first (empty array if no dependencies)",
-    "- acceptanceCriteria should be concrete, testable statements",
-    "- tier is how hard the HU is to implement right (trivial: a local change; standard: several files or one module; deep: design decisions, many modules, or security/migrations), and tierReason says why in one line",
-    "- Order stories so that dependencies are respected (a story should only depend on stories with lower ids)",
-    ...(criteria.length > 0 ? [
-      "- covers lists the numbers of the card's acceptance criteria this HU implements; EVERY card criterion must appear in the covers of at least one HU, and an HU's acceptanceCriteria must include each criterion it covers, verbatim",
-    ] : ["- covers is an empty array"])
-  );
-
-  return sections.join("\n\n");
-}
-
-/**
- * KJC-TSK-0989: the card's criteria no HU covers, by number and text.
- * @param {Array<{covers?: number[]}>} stories
- * @param {string[]} criteria
- * @returns {Array<{index: number, text: string}>}
- */
-export function uncoveredCriteria(stories, criteria) {
-  const covered = new Set(stories.flatMap((s) => s.covers ?? []));
-  return criteria.map((text, i) => ({ index: i + 1, text })).filter((c) => !covered.has(c.index));
-}
-
-/**
- * Parse the output from a decomposition prompt.
- * @param {string} raw - Raw text output from the agent.
- * @returns {Array<{id: string, title: string, role: string, goal: string, benefit: string, acceptanceCriteria: string[], dependsOn: string[]}>|null}
- */
-export function parseDecompositionOutput(raw) {
-  const parsed = extractFirstJson(raw);
-  if (!parsed || !Array.isArray(parsed.stories)) return null;
-
-  const stories = parsed.stories
-    .filter(s => s && s.id && s.title)
-    .map(s => ({
-      id: s.id,
-      title: s.title,
-      role: s.role || "developer",
-      goal: s.goal || s.title,
-      benefit: s.benefit || "",
-      acceptanceCriteria: Array.isArray(s.acceptanceCriteria) ? s.acceptanceCriteria : [],
-      dependsOn: Array.isArray(s.dependsOn) ? s.dependsOn : [],
-      covers: Array.isArray(s.covers) ? s.covers.map(Number).filter(Number.isInteger) : [],
-      tier: s.tier ?? null,
-      tierReason: s.tierReason ?? null
-    }));
-
-  return stories.length > 0 ? stories : null;
-}
-
-/**
- * Parse the raw output from the HU reviewer agent.
- * @param {string} raw - Raw text output from the agent.
- * @returns {object|null} Parsed result with evaluations and batch_summary, or null.
- */
-export function parseHuReviewerOutput(raw) {
-  const parsed = extractFirstJson(raw);
-  if (!parsed) return null;
-
-  if (!Array.isArray(parsed.evaluations)) return null;
-
-  const evaluations = parsed.evaluations
-    .map(parseEvaluation)
-    .filter(Boolean);
-
-  if (evaluations.length === 0) return null;
-
-  const certified = evaluations.filter(e => e.verdict === "certified").length;
-  const needsRewrite = evaluations.filter(e => e.verdict === "needs_rewrite").length;
-  const needsContext = evaluations.filter(e => e.verdict === "needs_context").length;
-
-  return {
-    evaluations,
-    batch_summary: {
-      total: evaluations.length,
-      certified,
-      needs_rewrite: needsRewrite,
-      needs_context: needsContext,
-      consolidated_questions: parsed.batch_summary?.consolidated_questions || ""
-    }
-  };
-}

package/src/prompts/tool-correctness-judge.js

@@ -1,31 +0,0 @@
-// KJC-TSK-0375 — Prompt builder for the ToolCorrectnessJudge role.
-// Inspired by deepeval's tool-correctness metric.
-
-const PREAMBLE = "IMPORTANT: You are running as a Karajan sub-agent. "
-  + "Do NOT use any MCP tools, do NOT mention Karajan. "
-  + "Your job is to judge another agent's tool choices.";
-
-export function buildToolCorrectnessJudgePrompt({ task, toolCalls, instructions }) {
-  const calls = toolCalls
-    .map((c, i) => `${i + 1}. **${c.tool}** — args: ${JSON.stringify(c.args)}`)
-    .join("\n");
-  const body = [
-    "You are the ToolCorrectnessJudge for Karajan Code.",
-    "Input: (a) a task description and (b) the ordered tool calls an LLM coder",
-    "made (Read/Edit/Write/Bash/Glob/Grep/MultiEdit). Judge each call on:",
-    "  - tool choice: right tool for the intent?",
-    "  - argument quality: paths plausible, commands valid, no garbage placeholders?",
-    "Per-call verdict: `correct=true|false` + one-sentence `reason`.",
-    "Aggregate into a single 0-100 score:",
-    "  - 100 = every call right with clean args",
-    "  - 70-99 = mostly right, minor missteps",
-    "  - 40-69 = several wrong choices, budget wasted",
-    "  - 0-39 = predominantly bad, retry advised",
-    "Return a single valid JSON object and nothing else.",
-    'Schema: {"score":0-100,"summary":string,"breakdown":[{"tool":string,"args":object,"correct":boolean,"reason":string}]}',
-  ].join("\n");
-  const sections = [PREAMBLE];
-  if (instructions) sections.push(instructions);
-  sections.push(body, `## Task\n${task}`, `## Tool calls (${toolCalls.length})\n${calls || "(no tool calls captured)"}`);
-  return sections.join("\n\n");
-}

package/src/prompts/triage.js

@@ -1,57 +0,0 @@
-const SUBAGENT_PREAMBLE = [
-  "IMPORTANT: You are running as a Karajan sub-agent.",
-  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
-  "Do NOT use any MCP tools. Focus only on task complexity triage."
-].join(" ");
-
-const ROLE_DESCRIPTIONS = [
-  { role: "planner", description: "Generates an implementation plan before coding. Useful for complex multi-file tasks." },
-  { role: "researcher", description: "Investigates the codebase for context before coding. Useful when understanding existing code is needed." },
-  { role: "tester", description: "Runs dedicated testing pass after coding. Ensures tests exist and pass." },
-  { role: "security", description: "Audits code for security vulnerabilities. Checks auth, input validation, injection risks." },
-  { role: "refactorer", description: "Cleans up and refactors code after the main implementation." },
-  { role: "reviewer", description: "Reviews the code diff for quality issues. Standard quality gate." },
-  { role: "architect", description: "Designs solution architecture — layers, patterns, data model, API contracts, tradeoffs. Activate when task creates new module/app, affects data model/APIs, complexity is medium/complex, or design is ambiguous." },
-  { role: "hu-reviewer", description: "Certifies user stories before coding. Activate for medium/complex tasks that need story decomposition." }
-];
-
-export function buildTriagePrompt({ task, instructions, availableRoles }) {
-  const sections = [SUBAGENT_PREAMBLE];
-
-  if (instructions) {
-    sections.push(instructions);
-  }
-
-  const roles = availableRoles || ROLE_DESCRIPTIONS;
-
-  sections.push(
-    "You are a task triage agent for Karajan Code, a multi-agent coding orchestrator.",
-    "Analyze the following task and determine which pipeline roles should be activated.",
-    "## Available Roles",
-    roles.map((r) => `- **${r.role}**: ${r.description}`).join("\n"),
-    "## Decision Guidelines",
-    [
-      "- **planner**: Enable for complex tasks (multi-file, architectural changes, data model changes). Disable for simple fixes.",
-      "- **researcher**: Enable when the task needs codebase context, API understanding, or investigation. Disable for standalone new files.",
-      "- **tester**: Enable for any task with logic, APIs, components, services. Disable ONLY for pure documentation, comments, or CSS-only changes.",
-      "- **security**: Enable for authentication, APIs, user input handling, data access, external integrations. Disable for UI-only or doc changes.",
-      "- **refactorer**: Enable only when explicitly requested or when the task is a refactoring task.",
-      "- **reviewer**: Enable for most tasks as a quality gate. Disable only for trivial, single-line changes.",
-      "- **architect**: Enable when creating new modules/apps, changing data models or APIs, medium/complex tasks, or when design approach is ambiguous. Disable for simple fixes, doc-only, or CSS-only changes.",
-      "- **hu-reviewer**: Enable for medium/complex tasks that benefit from story decomposition and certification. Disable for trivial/simple tasks, doc-only, or CSS-only changes.",
-      "- **audit/analysis taskType**: Set taskType to \"audit\" or \"analysis\" for tasks that only require reading/inspecting code without making changes (e.g., audit, review, analyze, check, verify, inspect, scan, auditar, revisar, analizar, comprobar, verificar, inspeccionar). The coder and reviewer will be skipped entirely for these tasks.",
-      "- **no-code taskType**: Use no-code when the task is about data analysis, document generation, SQL queries, CSV transformation, report generation, or any non-programming task. The coder will generate output (not source code), and TDD/SonarQube will be disabled. The reviewer still runs to validate logic/correctness.",
-      "",
-      "Note: coder is ALWAYS active for coding tasks — you don't need to decide on it. However, for audit/analysis taskTypes the coder is skipped."
-    ].join("\n"),
-    "Classify the task complexity, determine its taskType, recommend only the necessary pipeline roles, and assess whether the task should be decomposed into smaller subtasks.",
-    "Keep the reasoning short and practical.",
-    "Return a single valid JSON object and nothing else.",
-    'JSON schema: {"level":"trivial|simple|medium|complex","roles":["planner|researcher|refactorer|reviewer|tester|security|architect|hu-reviewer"],"taskType":"sw|infra|doc|add-tests|refactor|audit|analysis|no-code","reasoning":string,"shouldDecompose":boolean,"subtasks":string[]}',
-    `## Task\n${task}`
-  );
-
-  return sections.join("\n\n");
-}
-
-export { ROLE_DESCRIPTIONS };

package/src/rag/embedder.js

@@ -1,2 +0,0 @@
-// Shim: embedder now lives in karajan-core/rag (KJC-TSK-0632 PR3).
-export * from "karajan-core/rag/embedder";

package/src/rag/embedders/_cloud-base.js

@@ -1,2 +0,0 @@
-// Shim: moved to karajan-core/rag/embedders (KJC-TSK-0632 PR3).
-export * from "karajan-core/rag/embedders/_cloud-base";

package/src/rag/embedders/cohere.js

@@ -1,2 +0,0 @@
-// Shim: moved to karajan-core/rag/embedders (KJC-TSK-0632 PR3).
-export * from "karajan-core/rag/embedders/cohere";

package/src/rag/embedders/mistral.js

@@ -1,2 +0,0 @@
-// Shim: moved to karajan-core/rag/embedders (KJC-TSK-0632 PR3).
-export * from "karajan-core/rag/embedders/mistral";

package/src/rag/embedders/onnx.js

@@ -1,2 +0,0 @@
-// Shim: moved to karajan-core/rag/embedders (KJC-TSK-0632 PR3).
-export * from "karajan-core/rag/embedders/onnx";

package/src/rag/embedders/openai.js

@@ -1,2 +0,0 @@
-// Shim: moved to karajan-core/rag/embedders (KJC-TSK-0632 PR3).
-export * from "karajan-core/rag/embedders/openai";

package/src/rag/embedders/voyage.js

@@ -1,2 +0,0 @@
-// Shim: moved to karajan-core/rag/embedders (KJC-TSK-0632 PR3).
-export * from "karajan-core/rag/embedders/voyage";

package/src/rag/rerank.js

@@ -1,4 +0,0 @@
-// Shim: rerank now lives in karajan-core/rag so the hu-board workspace
-// can consume it without a relative dep on the CLI src tree.
-// KJC-TSK-0632 PR2.
-export { RerankError, _resetPipeline, rerank } from "karajan-core/rag/rerank";

package/src/rag/where-parser.js

@@ -1,4 +0,0 @@
-// Shim: where-parser now lives in karajan-core/rag so the hu-board
-// workspace can consume it without a relative dep on the CLI src tree.
-// KJC-TSK-0632 PR2.
-export { parseWhere, buildWhereSql } from "karajan-core/rag/where-parser";

package/src/repeat-detector.js

@@ -1,88 +0,0 @@
-import { createHash } from "node:crypto";
-
-const DEFAULT_THRESHOLD = 2;
-
-function normalizeIssueKey(value) {
-  if (value === null || value === undefined) return "";
-  return String(value).trim();
-}
-
-function buildIssueSignature(issues, keySelector) {
-  const counts = new Map();
-  for (const issue of issues || []) {
-    const key = normalizeIssueKey(keySelector(issue));
-    if (!key) continue;
-    counts.set(key, (counts.get(key) || 0) + 1);
-  }
-  if (counts.size === 0) return "";
-  return Array.from(counts.entries())
-    .sort(([a], [b]) => a.localeCompare(b))
-    .map(([key, count]) => `${key}:${count}`)
-    .join("|");
-}
-
-function hashSignature(signature) {
-  if (!signature) return "";
-  return createHash("sha256").update(signature).digest("hex");
-}
-
-function updateRepeatState(state, signatureHash) {
-  if (!signatureHash) {
-    return { lastHash: null, repeatCount: 0 };
-  }
-  const nextCount = signatureHash === state.lastHash ? state.repeatCount + 1 : 1;
-  return { lastHash: signatureHash, repeatCount: nextCount };
-}
-
-function parseThreshold(value) {
-  const parsed = Number(value);
-  if (Number.isFinite(parsed) && parsed > 0) return parsed;
-  return DEFAULT_THRESHOLD;
-}
-
-export function getRepeatThreshold(config) {
-  const raw =
-    config?.failFast?.repeatThreshold ??
-    config?.session?.repeat_detection_threshold ??
-    config?.session?.fail_fast_repeats ??
-    2;
-  const value = Number(raw);
-  if (Number.isFinite(value) && value > 0) return value;
-  return 2;
-}
-
-export class RepeatDetector {
-  constructor({ threshold = DEFAULT_THRESHOLD } = {}) {
-    this.threshold = parseThreshold(threshold);
-    this.sonar = { lastHash: null, repeatCount: 0 };
-    this.reviewer = { lastHash: null, repeatCount: 0 };
-  }
-
-  addIteration(sonarIssues, reviewerIssues) {
-    const sonarSignature = buildIssueSignature(
-      sonarIssues || [],
-      (issue) => issue?.rule || issue?.message
-    );
-    const reviewerSignature = buildIssueSignature(
-      reviewerIssues || [],
-      (issue) => issue?.description || issue?.content || issue?.id
-    );
-
-    this.sonar = updateRepeatState(this.sonar, hashSignature(sonarSignature));
-    this.reviewer = updateRepeatState(this.reviewer, hashSignature(reviewerSignature));
-  }
-
-  isStalled() {
-    if (this.sonar.repeatCount >= this.threshold) {
-      return { stalled: true, reason: "sonar_repeat" };
-    }
-    if (this.reviewer.repeatCount >= this.threshold) {
-      return { stalled: true, reason: "reviewer_repeat" };
-    }
-    return { stalled: false, reason: "" };
-  }
-
-  getRepeatCounts() {
-    return { sonar: this.sonar.repeatCount, reviewer: this.reviewer.repeatCount };
-  }
-}

package/src/review/diff-generator.js

@@ -1,112 +0,0 @@
-import { runCommand } from "../utils/process.js";
-import { generateSnapshotDiff } from "./snapshot-diff.js";
-import { getRunContext } from "../utils/run-context.js";
-
-// Module-scope back-compat state for callers outside a `withRunContext`
-// scope. When inside a pipeline, `getRunContext()` provides per-run
-// isolation (TSK-0338) — the module-level values below are only consulted
-// as a last resort.
-
-/** @type {((command: string, args?: string[], options?: object) => Promise<object>)|null} */
-let _runner = null;
-
-/** @type {Map<string, string>|null} — pre-coder filesystem snapshot for git-free diff */
-let _snapshot = null;
-
-/** @type {string|null} — project directory scope for git diff (prevents leaking unrelated changes) */
-let _projectDir = null;
-
-/** Retained for back-compat; pipelines should use `withRunContext({ projectDir })` for isolation. */
-export function setProjectDir(dir) {
-  _projectDir = dir;
-}
-
-/** Retained for back-compat; pipelines should use `withRunContext({ snapshot })` for isolation. */
-export function setSnapshot(snapshot) {
-  _snapshot = snapshot;
-}
-
-/** Retained for back-compat; pipelines should use `withRunContext({ runner })` for isolation. */
-export function setRunner(runner) {
-  _runner = runner;
-}
-
-function resolveRunner() {
-  return getRunContext()?.runner || _runner || runCommand;
-}
-
-function resolveProjectDir() {
-  const ctx = getRunContext();
-  if (ctx && "projectDir" in ctx) return ctx.projectDir;
-  return _projectDir;
-}
-
-function resolveSnapshot() {
-  const ctx = getRunContext();
-  if (ctx && "snapshot" in ctx) return ctx.snapshot;
-  return _snapshot;
-}
-
-function run(command, args, ...rest) {
-  return resolveRunner()(command, args, ...rest);
-}
-
-export async function computeBaseRef({ baseBranch = "main", baseRef = null }) {
-  if (baseRef) return baseRef;
-
-  try {
-    const mergeBase = await run("git", ["merge-base", "HEAD", `origin/${baseBranch}`]);
-    if (mergeBase.exitCode === 0) return mergeBase.stdout.trim();
-
-    const fallback = await run("git", ["rev-parse", "HEAD~1"]);
-    if (fallback.exitCode === 0) return fallback.stdout.trim();
-
-    // Empty repo (zero commits): diff against the empty tree
-    const emptyTree = await run("git", ["hash-object", "-t", "tree", "/dev/null"]);
-    if (emptyTree.exitCode === 0) return emptyTree.stdout.trim();
-  } catch { /* git not available */ }
-
-  // No git or all strategies failed — return sentinel for snapshot-based diff
-  return "__snapshot__";
-}
-
-export async function generateDiff({ baseRef, stageNewFiles = false, projectDir = null }) {
-  // Auto-resolve projectDir from run context (TSK-0338) or module fallback
-  const scopeDir = projectDir || resolveProjectDir() || null;
-  const snapshot = resolveSnapshot();
-
-  // Try git diff first
-  try {
-    if (stageNewFiles) {
-      const addArgs = scopeDir ? ["-A", scopeDir] : ["-A"];
-      await run("git", ["add", ...addArgs]);
-    }
-    const diffArgs = ["diff", stageNewFiles ? "--cached" : "", `${baseRef}`].filter(Boolean);
-    // Scope diff to projectDir when it's a subdirectory (prevents leaking unrelated changes)
-    if (scopeDir) diffArgs.push("--", scopeDir);
-    const result = await run("git", diffArgs);
-    if (result.exitCode === 0) {
-      return result.stdout;
-    }
-  } catch { /* git not available or failed */ }
-
-  // Fallback: snapshot-based diff (no git needed)
-  if (snapshot) {
-    const dir = projectDir || process.cwd();
-    return generateSnapshotDiff(snapshot, null, dir);
-  }
-
-  // No git and no snapshot — generate diff of all files as new.
-  // TSK-0340: dropped a stray `const { takeSnapshot } = await import(...)`
-  // that was never used in this branch (we synthesize an empty Map and
-  // let generateSnapshotDiff do the file walk itself).
-  const dir = projectDir || process.cwd();
-  const emptySnapshot = new Map();
-  return generateSnapshotDiff(emptySnapshot, null, dir);
-}
-
-export async function getUntrackedFiles(cwd = null) {
-  const result = await run("git", ["ls-files", "--others", "--exclude-standard"], cwd ? { cwd } : {});
-  if (result.exitCode !== 0) return [];
-  return result.stdout.trim().split("\n").filter(Boolean);
-}