git-coco 0.43.0 → 0.45.0

package/dist/index.esm.mjs

@@ -54,7 +54,7 @@ import { pathToFileURL } from 'url';
 /**
  * Current build version from package.json
  */
-const BUILD_VERSION = "0.43.0";
+const BUILD_VERSION = "0.45.0";
 
 const isInteractive = (config) => {
     return config?.mode === 'interactive' || !!config?.interactive;
@@ -1228,6 +1228,18 @@ const schema$1 = {
                     "$ref": "#/definitions/DynamicModelPreference",
                     "description": "Default dynamic routing preference when model is set to \"dynamic\".",
                     "default": "balanced"
+                },
+                "fastPath": {
+                    "type": "object",
+                    "properties": {
+                        "markdown": {
+                            "type": "boolean",
+                            "description": "Replace the LLM summary with a templated heading extract for `.md` / `.mdx` / `.markdown` modification diffs that have clear heading-level structural changes. Diffs without structural signals (paragraph-only edits) still go to the LLM regardless of this flag.\n\nBench impact (synthetic): collapses docs-update-shaped commits from ~24s cold to ~3ms (no LLM calls fire for the markdown files). Real-world wall-clock savings depend on per-call LLM latency.",
+                            "default": false
+                        }
+                    },
+                    "additionalProperties": false,
+                    "description": "Opt-in fast paths that trade summary detail for speed. Each flag here replaces an LLM summary call with a deterministic templated extract for a specific file shape. Off by default — when enabled, you accept that final commit messages on those file shapes may be blander than LLM-generated summaries (the templated extract names structural changes only).\n\nLossless optimizations (cache, trivial-shape skip on pure additions / deletions / renames / binary, sort discipline) ship default-on and are not configured here."
                 }
             },
             "required": [
@@ -1641,6 +1653,18 @@ const schema$1 = {
                     "$ref": "#/definitions/DynamicModelPreference",
                     "description": "Default dynamic routing preference when model is set to \"dynamic\".",
                     "default": "balanced"
+                },
+                "fastPath": {
+                    "type": "object",
+                    "properties": {
+                        "markdown": {
+                            "type": "boolean",
+                            "description": "Replace the LLM summary with a templated heading extract for `.md` / `.mdx` / `.markdown` modification diffs that have clear heading-level structural changes. Diffs without structural signals (paragraph-only edits) still go to the LLM regardless of this flag.\n\nBench impact (synthetic): collapses docs-update-shaped commits from ~24s cold to ~3ms (no LLM calls fire for the markdown files). Real-world wall-clock savings depend on per-call LLM latency.",
+                            "default": false
+                        }
+                    },
+                    "additionalProperties": false,
+                    "description": "Opt-in fast paths that trade summary detail for speed. Each flag here replaces an LLM summary call with a deterministic templated extract for a specific file shape. Off by default — when enabled, you accept that final commit messages on those file shapes may be blander than LLM-generated summaries (the templated extract names structural changes only).\n\nLossless optimizations (cache, trivial-shape skip on pure additions / deletions / renames / binary, sort discipline) ship default-on and are not configured here."
                 }
             },
             "required": [
@@ -1797,6 +1821,18 @@ const schema$1 = {
                     "$ref": "#/definitions/DynamicModelPreference",
                     "description": "Default dynamic routing preference when model is set to \"dynamic\".",
                     "default": "balanced"
+                },
+                "fastPath": {
+                    "type": "object",
+                    "properties": {
+                        "markdown": {
+                            "type": "boolean",
+                            "description": "Replace the LLM summary with a templated heading extract for `.md` / `.mdx` / `.markdown` modification diffs that have clear heading-level structural changes. Diffs without structural signals (paragraph-only edits) still go to the LLM regardless of this flag.\n\nBench impact (synthetic): collapses docs-update-shaped commits from ~24s cold to ~3ms (no LLM calls fire for the markdown files). Real-world wall-clock savings depend on per-call LLM latency.",
+                            "default": false
+                        }
+                    },
+                    "additionalProperties": false,
+                    "description": "Opt-in fast paths that trade summary detail for speed. Each flag here replaces an LLM summary call with a deterministic templated extract for a specific file shape. Off by default — when enabled, you accept that final commit messages on those file shapes may be blander than LLM-generated summaries (the templated extract names structural changes only).\n\nLossless optimizations (cache, trivial-shape skip on pure additions / deletions / renames / binary, sort discipline) ship default-on and are not configured here."
                 }
             },
             "required": [
@@ -7890,6 +7926,109 @@ async function summarize(documents, { chain, textSplitter, options, logger, toke
     return res.text && res.text.trim();
 }
 
+/**
+ * Markdown-aware fast path (#861, angle 5). For modification diffs to
+ * `.md` / `.mdx` / `.markdown` files, build a templated summary from
+ * the changed structure (added / removed / updated headings) instead
+ * of paying for an LLM call. Mirrors `trivialDiff` from #845: a deterministic
+ * skip when the diff's meaning is captured by its shape.
+ *
+ * Quality / cost trade-off, on purpose: LLM summaries of markdown edits
+ * are wordier ("expanded the configuration section with new examples,
+ * fixed typos in troubleshooting") but most of that detail isn't load-
+ * bearing for a commit message. The templated summary names the
+ * structural changes (which sections moved) plus a +/- line count, and
+ * defers to the LLM only when the diff has no clear structural signals
+ * (paragraph-only edits, where a templated summary would actually drop
+ * useful context).
+ */
+const MARKDOWN_EXTENSIONS = ['.md', '.markdown', '.mdx'];
+const MAX_HEADINGS_PER_BUCKET = 6;
+function isMarkdownFile(path) {
+    const lower = path.toLowerCase();
+    return MARKDOWN_EXTENSIONS.some((ext) => lower.endsWith(ext));
+}
+function summarizeMarkdownDiff(fileDiff) {
+    if (!isMarkdownFile(fileDiff.file))
+        return undefined;
+    const addedHeadings = new Set();
+    const removedHeadings = new Set();
+    let addedLines = 0;
+    let removedLines = 0;
+    for (const line of fileDiff.diff.split('\n')) {
+        if (isHeaderLine$1(line))
+            continue;
+        if (line.startsWith('+')) {
+            addedLines++;
+            const heading = parseHeading(line.slice(1));
+            if (heading)
+                addedHeadings.add(heading);
+        }
+        else if (line.startsWith('-')) {
+            removedLines++;
+            const heading = parseHeading(line.slice(1));
+            if (heading)
+                removedHeadings.add(heading);
+        }
+    }
+    // No content change → nothing to summarize. Caller falls through.
+    if (addedLines === 0 && removedLines === 0)
+        return undefined;
+    // No structural signal → fall through to LLM. We only fast-path
+    // when the diff has heading-level changes; pure paragraph edits go
+    // to the LLM so the summary keeps its detail.
+    if (addedHeadings.size === 0 && removedHeadings.size === 0) {
+        return undefined;
+    }
+    // A heading that appears in both buckets is likely an update (kept
+    // around but its body changed) rather than two distinct events.
+    // The naive split-by-bucket diff format used by git emits the old
+    // text under `-` and the new text under `+`; an unchanged heading
+    // line shouldn't show up in either bucket via the standard hunk
+    // path, but defensively de-dupe in case the diff producer emits
+    // surrounding context as +/-.
+    const updated = new Set([...addedHeadings].filter((h) => removedHeadings.has(h)));
+    const purelyAdded = [...addedHeadings].filter((h) => !updated.has(h));
+    const purelyRemoved = [...removedHeadings].filter((h) => !updated.has(h));
+    const parts = [`Updated markdown \`${fileDiff.file}\``];
+    if (purelyAdded.length) {
+        parts.push(`new sections: ${formatHeadingList(purelyAdded)}`);
+    }
+    if (purelyRemoved.length) {
+        parts.push(`removed sections: ${formatHeadingList(purelyRemoved)}`);
+    }
+    if (updated.size) {
+        parts.push(`updated sections: ${formatHeadingList([...updated])}`);
+    }
+    parts.push(`+${addedLines}/-${removedLines} lines`);
+    return `${parts.join('. ')}.`;
+}
+function formatHeadingList(headings) {
+    if (headings.length <= MAX_HEADINGS_PER_BUCKET) {
+        return headings.join(', ');
+    }
+    const shown = headings.slice(0, MAX_HEADINGS_PER_BUCKET);
+    const remainder = headings.length - shown.length;
+    return `${shown.join(', ')} (+${remainder} more)`;
+}
+function isHeaderLine$1(line) {
+    return (line.startsWith('diff --git') ||
+        line.startsWith('index ') ||
+        line.startsWith('--- ') ||
+        line.startsWith('+++ ') ||
+        line.startsWith('@@') ||
+        line.startsWith('new file mode') ||
+        line.startsWith('deleted file mode') ||
+        line.startsWith('similarity index') ||
+        line.startsWith('rename from ') ||
+        line.startsWith('rename to ') ||
+        line.startsWith('Binary files '));
+}
+function parseHeading(line) {
+    const match = line.match(/^#{1,6}\s+(.+?)\s*$/);
+    return match ? match[1].trim() : undefined;
+}
+
 /**
  * Inspect a unified-diff string and report its shape, or undefined
  * if the diff isn't trivial (mixed +/- lines, weird headers, etc.).
@@ -8027,7 +8166,7 @@ function isCacheEnabled$1() {
  * synthetic summaries usually drop the directory token totals under
  * budget so wave consolidation skips too.
  */
-async function summarizeFileDiff(fileDiff, { chain, textSplitter, tokenizer, logger, metadata, }) {
+async function summarizeFileDiff(fileDiff, { chain, textSplitter, tokenizer, logger, metadata, fastPath, }) {
     const trivialSummary = summarizeTrivialDiff(fileDiff);
     if (trivialSummary !== undefined) {
         logger.verbose(` - ${fileDiff.file}: trivial-shape skip (no LLM call)`, { color: 'gray' });
@@ -8037,6 +8176,25 @@ async function summarizeFileDiff(fileDiff, { chain, textSplitter, tokenizer, log
             tokenCount: tokenizer(trivialSummary),
         };
     }
+    // Markdown fast path (#861, angle 5). Opt-in via `fastPath.markdown`
+    // because it's a lossy optimization: the templated summary names
+    // structural changes only and drops body-text detail that an LLM
+    // summary would carry. Off by default; users who prefer summary
+    // fidelity over speed (which is the safer default for commit-message
+    // generation downstream) keep the LLM path. When the flag IS on, the
+    // fast path still falls through to the LLM for paragraph-only edits
+    // where a templated summary would lose useful context.
+    if (fastPath?.markdown) {
+        const markdownSummary = summarizeMarkdownDiff(fileDiff);
+        if (markdownSummary !== undefined) {
+            logger.verbose(` - ${fileDiff.file}: markdown fast-path skip (no LLM call)`, { color: 'gray' });
+            return {
+                ...fileDiff,
+                diff: markdownSummary,
+                tokenCount: tokenizer(markdownSummary),
+            };
+        }
+    }
     // Cache lookup (#845, PR 5). Keyed on the file's literal diff
     // content + the active model + the summarization prompt hash.
     // A hit returns the prior summary instantly; on iterative
@@ -8148,7 +8306,7 @@ function createLimit$2(maxConcurrent) {
  * @returns Array of file diffs with large files summarized
  */
 async function summarizeLargeFiles(diffs, options) {
-    const { maxFileTokens, minTokensForSummary, maxConcurrent, tokenizer, logger, chain, textSplitter, metadata } = options;
+    const { maxFileTokens, minTokensForSummary, maxConcurrent, maxTokens, fastPath, tokenizer, logger, chain, textSplitter, metadata, } = options;
     // Identify files that need summarization
     const filesToSummarize = [];
     const results = [...diffs];
@@ -8160,17 +8318,57 @@ async function summarizeLargeFiles(diffs, options) {
     if (filesToSummarize.length === 0) {
         return results;
     }
-    logger.verbose(`Pre-summarizing ${filesToSummarize.length} large file(s)...`, { color: 'blue' });
-    // Process large files in waves
-    const summarizedFiles = await processInWaves$1(filesToSummarize, async ({ diff }) => summarizeFileDiff(diff, { chain, textSplitter, tokenizer, logger, metadata }), maxConcurrent);
-    // Update results with summarized files
-    summarizedFiles.forEach((summarizedDiff, i) => {
+    // Incremental termination (#861, PR 1). When the caller supplies a
+    // budget, dispatch biggest-first and re-check the running total per
+    // dispatch — once earlier completions drop the total under maxTokens,
+    // the remaining queued files skip the LLM and keep their raw diffs.
+    // Mirrors the Phase 3 pattern in `summarizeDiffs.ts`. Without a
+    // budget (undefined), behavior matches the prior path: every
+    // eligible file is summarized regardless.
+    filesToSummarize.sort((a, b) => b.diff.tokenCount - a.diff.tokenCount);
+    const incrementalTermination = maxTokens !== undefined;
+    let runningTotal = diffs.reduce((sum, diff) => sum + diff.tokenCount, 0);
+    let summarizedCount = 0;
+    let skippedCount = 0;
+    logger.verbose(`Pre-summarizing up to ${filesToSummarize.length} large file(s)...`, { color: 'blue' });
+    const processed = await processInWaves$1(filesToSummarize, async ({ diff }) => {
+        // Re-check the budget at dispatch time when the caller supplied
+        // one. Earlier completions may have already dropped the total
+        // under the cap; in that case skip the LLM call entirely and
+        // keep the raw diff. Without a budget, every eligible file is
+        // summarized (preserves the prior behavior).
+        if (incrementalTermination && runningTotal <= maxTokens) {
+            return { diff, summarized: false };
+        }
+        const summarized = await summarizeFileDiff(diff, {
+            chain,
+            textSplitter,
+            tokenizer,
+            logger,
+            metadata,
+            fastPath,
+        });
+        const delta = diff.tokenCount - summarized.tokenCount;
+        if (delta > 0) {
+            runningTotal -= delta;
+        }
+        return { diff: summarized, summarized: true };
+    }, maxConcurrent);
+    processed.forEach((entry, i) => {
         const originalIndex = filesToSummarize[i].index;
+        if (!entry.summarized) {
+            skippedCount++;
+            return;
+        }
+        summarizedCount++;
         const originalTokens = results[originalIndex].tokenCount;
-        const newTokens = summarizedDiff.tokenCount;
-        logger.verbose(` - ${summarizedDiff.file}: ${originalTokens} -> ${newTokens} tokens`, { color: 'magenta' });
-        results[originalIndex] = summarizedDiff;
+        const newTokens = entry.diff.tokenCount;
+        logger.verbose(` - ${entry.diff.file}: ${originalTokens} -> ${newTokens} tokens`, { color: 'magenta' });
+        results[originalIndex] = entry.diff;
     });
+    if (skippedCount > 0) {
+        logger.verbose(`Skipped ${skippedCount} pre-summary call(s) — token budget already met after ${summarizedCount} earlier file(s)`, { color: 'cyan' });
+    }
     return results;
 }
 /**
@@ -8436,7 +8634,7 @@ async function summarizeDiffs(rootDiffNode, { tokenizer, logger,
 // with the service defaults means a caller that omits
 // `maxTokens` doesn't accidentally fall into a tighter budget
 // than the rest of the system assumes.
-maxTokens = 4096, minTokensForSummary = 400, maxFileTokens, maxConcurrent = 6, textSplitter, chain, metadata, handleOutput = defaultOutputCallback, }) {
+maxTokens = 4096, minTokensForSummary = 400, maxFileTokens, maxConcurrent = 6, fastPath, textSplitter, chain, metadata, handleOutput = defaultOutputCallback, }) {
     // Calculate maxFileTokens as 25% of maxTokens if not specified
     const effectiveMaxFileTokens = maxFileTokens ?? Math.floor(maxTokens * 0.25);
     // PHASE 1: Directory grouping & assessment
@@ -8460,6 +8658,13 @@ maxTokens = 4096, minTokensForSummary = 400, maxFileTokens, maxConcurrent = 6, t
         maxFileTokens: effectiveMaxFileTokens,
         minTokensForSummary,
         maxConcurrent,
+        // #861, PR 1: pass the overall budget so Phase 2 can short-circuit
+        // once earlier completions drop the running total under the cap.
+        maxTokens,
+        // #861, angle 5: opt-in markdown fast path. Off by default; when
+        // enabled, markdown modification diffs with structural signals
+        // resolve via a templated extract instead of an LLM call.
+        fastPath,
         tokenizer,
         logger,
         chain,
@@ -11437,7 +11642,7 @@ for (var i = 0; i < 256; i++) {
   simpleEscapeMap[i] = simpleEscapeSequence(i);
 }
 
-async function fileChangeParser({ changes, commit, options: { tokenizer, git, llm: model, logger, maxTokens, minTokensForSummary, maxFileTokens, maxConcurrent, metadata, }, }) {
+async function fileChangeParser({ changes, commit, options: { tokenizer, git, llm: model, logger, maxTokens, minTokensForSummary, maxFileTokens, maxConcurrent, fastPath, metadata, }, }) {
     const textSplitter = new RecursiveCharacterTextSplitter({ chunkSize: 10000, chunkOverlap: 250 });
     const summarizationChain = loadSummarizationChain(model, {
         type: 'map_reduce',
@@ -11469,6 +11674,7 @@ async function fileChangeParser({ changes, commit, options: { tokenizer, git, ll
         minTokensForSummary,
         maxFileTokens,
         maxConcurrent,
+        fastPath,
         textSplitter,
         chain: summarizationChain,
         logger,
@@ -11488,6 +11694,7 @@ function createFileChangeParserOptions({ command, git, llm, logger, model, provi
         minTokensForSummary: service?.minTokensForSummary,
         maxFileTokens: service?.maxFileTokens,
         maxConcurrent: service?.maxConcurrent,
+        fastPath: service?.fastPath,
         metadata: {
             command,
             provider,
@@ -12415,6 +12622,164 @@ const CommitSplitPlanSchema = objectType({
     }))
         .min(1),
 });
+
+const getGroupFiles$1 = (group) => group.files || [];
+const getGroupHunks$1 = (group) => group.hunks || [];
+function getPlanValidationIssues(plan, staged, hunkInventory) {
+    const stagedFiles = new Set(staged.map((change) => change.filePath));
+    const seen = new Set();
+    const seenHunks = new Set();
+    const unknownFiles = [];
+    const duplicateFiles = [];
+    const unknownHunks = [];
+    const duplicateHunks = [];
+    plan.groups.forEach((group) => {
+        getGroupFiles$1(group).forEach((file) => {
+            if (!stagedFiles.has(file)) {
+                unknownFiles.push(file);
+                return;
+            }
+            if (seen.has(file)) {
+                duplicateFiles.push(file);
+                return;
+            }
+            seen.add(file);
+        });
+        getGroupHunks$1(group).forEach((hunkId) => {
+            const hunk = hunkInventory?.byId.get(hunkId);
+            if (!hunk) {
+                unknownHunks.push(hunkId);
+                return;
+            }
+            if (seenHunks.has(hunkId)) {
+                duplicateHunks.push(hunkId);
+                return;
+            }
+            seenHunks.add(hunkId);
+        });
+    });
+    const hunkCoveredFiles = new Set([...seenHunks].map((hunkId) => hunkInventory?.byId.get(hunkId)?.filePath));
+    const mixedFiles = [...seen].filter((file) => hunkCoveredFiles.has(file));
+    const partiallyCoveredFiles = [...hunkCoveredFiles]
+        .filter((file) => Boolean(file))
+        .filter((file) => {
+        const fileHunks = hunkInventory?.byFile.get(file) || [];
+        return fileHunks.some((hunk) => !seenHunks.has(hunk.id));
+    });
+    const missingFiles = [...stagedFiles].filter((file) => !seen.has(file) && !hunkCoveredFiles.has(file));
+    return {
+        unknownFiles,
+        duplicateFiles,
+        unknownHunks,
+        duplicateHunks,
+        mixedFiles,
+        partiallyCoveredFiles,
+        missingFiles,
+    };
+}
+function hasPlanValidationIssues(issues) {
+    return (issues.unknownFiles.length > 0 ||
+        issues.duplicateFiles.length > 0 ||
+        issues.unknownHunks.length > 0 ||
+        issues.duplicateHunks.length > 0 ||
+        issues.mixedFiles.length > 0 ||
+        issues.partiallyCoveredFiles.length > 0 ||
+        issues.missingFiles.length > 0);
+}
+function formatPlanValidationIssuesError(issues) {
+    return [
+        issues.unknownFiles.length ? `unknown files: ${issues.unknownFiles.join(', ')}` : undefined,
+        issues.duplicateFiles.length
+            ? `duplicate files: ${issues.duplicateFiles.join(', ')}`
+            : undefined,
+        issues.unknownHunks.length ? `unknown hunks: ${issues.unknownHunks.join(', ')}` : undefined,
+        issues.duplicateHunks.length
+            ? `duplicate hunks: ${issues.duplicateHunks.join(', ')}`
+            : undefined,
+        issues.mixedFiles.length
+            ? `files assigned both as whole files and hunks: ${issues.mixedFiles.join(', ')}`
+            : undefined,
+        issues.partiallyCoveredFiles.length
+            ? `files with only some hunks assigned: ${issues.partiallyCoveredFiles.join(', ')}`
+            : undefined,
+        issues.missingFiles.length ? `missing files: ${issues.missingFiles.join(', ')}` : undefined,
+    ]
+        .filter(Boolean)
+        .join('; ');
+}
+function formatPlanValidationFeedback(issues) {
+    const sections = [];
+    if (issues.unknownFiles.length) {
+        sections.push(`Files referenced that are NOT in the staged file inventory (remove or replace): ${issues.unknownFiles.join(', ')}`);
+    }
+    if (issues.duplicateFiles.length) {
+        sections.push(`Files assigned to more than one group (each file may appear at most once): ${issues.duplicateFiles.join(', ')}`);
+    }
+    if (issues.unknownHunks.length) {
+        sections.push(`Hunk IDs referenced that are NOT in the staged hunk inventory: ${issues.unknownHunks.join(', ')}`);
+    }
+    if (issues.duplicateHunks.length) {
+        sections.push(`Hunk IDs assigned to more than one group (each hunk may appear at most once): ${issues.duplicateHunks.join(', ')}`);
+    }
+    if (issues.mixedFiles.length) {
+        sections.push(`Files assigned BOTH as whole files and via hunks (pick one mode per file): ${issues.mixedFiles.join(', ')}`);
+    }
+    if (issues.partiallyCoveredFiles.length) {
+        sections.push(`Files with only some hunks assigned (every hunk for these files must be covered): ${issues.partiallyCoveredFiles.join(', ')}`);
+    }
+    if (issues.missingFiles.length) {
+        sections.push(`Staged files missing from every group (must appear exactly once): ${issues.missingFiles.join(', ')}`);
+    }
+    return sections.map((section) => `- ${section}`).join('\n');
+}
+
+const NO_PREVIOUS_FEEDBACK_PLACEHOLDER = 'None — this is the first attempt.';
+const DEFAULT_MAX_PLAN_ATTEMPTS = 3;
+/**
+ * Generate a commit-split plan with self-correcting retries on validator failures.
+ *
+ * The first attempt runs as normal. If `validatePlanForStagedFiles` rejects the result,
+ * the validator's complaints are formatted as natural-language feedback and fed back
+ * into the same prompt template (`previous_attempt_feedback` slot) so the model can
+ * fix its own mistakes without re-running pre-processing.
+ */
+async function generateValidatedCommitSplitPlan({ llm, prompt, variables, staged, hunkInventory, logger, tokenizer, metadata = {}, maxAttempts = DEFAULT_MAX_PLAN_ATTEMPTS, }) {
+    let lastIssues = null;
+    let attempt = 0;
+    while (attempt < maxAttempts) {
+        attempt++;
+        const previousFeedback = lastIssues
+            ? formatPlanValidationFeedback(lastIssues)
+            : NO_PREVIOUS_FEEDBACK_PLACEHOLDER;
+        const plan = await executeChainWithSchema(CommitSplitPlanSchema, llm, prompt, {
+            ...variables,
+            previous_attempt_feedback: previousFeedback,
+        }, {
+            logger,
+            tokenizer,
+            metadata: {
+                task: 'commit-split-plan',
+                ...metadata,
+                planAttempt: attempt,
+            },
+        });
+        const issues = getPlanValidationIssues(plan, staged, hunkInventory);
+        if (!hasPlanValidationIssues(issues)) {
+            if (attempt > 1 && logger) {
+                logger.verbose(`Plan validated after ${attempt} attempts.`, { color: 'green' });
+            }
+            return { plan, attempts: attempt };
+        }
+        lastIssues = issues;
+        if (logger) {
+            logger.verbose(`Plan attempt ${attempt}/${maxAttempts} failed validation: ${formatPlanValidationIssuesError(issues)}`, { color: 'yellow' });
+        }
+    }
+    throw new Error(lastIssues
+        ? `Failed to produce a valid commit-split plan after ${maxAttempts} attempts. Final validator issues: ${formatPlanValidationIssuesError(lastIssues)}`
+        : `Failed to produce a valid commit-split plan after ${maxAttempts} attempts.`);
+}
+
 const COMMIT_SPLIT_PROMPT = PromptTemplate.fromTemplate(`You are helping split staged git changes into a small sequence of coherent commits.
 
 Return ONLY valid JSON matching this schema:
@@ -12431,14 +12796,13 @@ Return ONLY valid JSON matching this schema:
 }}
 
 Rules:
-- Use each staged file exactly once.
-- If a file has hunk IDs and contains unrelated changes, assign every hunk ID exactly once instead of assigning the whole file.
-- Do not list the same file in "files" when assigning that file through "hunks".
-- Only use file paths listed in the staged file inventory.
-- Only use hunk IDs listed in the staged hunk inventory.
+- Every staged file MUST be assigned exactly once across all groups, either via "files" OR via every one of its hunk IDs (never both).
+- If you assign any hunk for a file, you MUST assign EVERY hunk for that file across the groups — partial coverage is invalid.
+- Do not list the same file in "files" of more than one group, and do not assign the same hunk ID to more than one group.
+- Only use file paths listed in the staged file inventory. Do not invent files.
+- Only use hunk IDs listed in the staged hunk inventory. Do not invent hunk IDs.
 - Prefer 2-5 commits unless the changes are truly all one topic.
 - Keep commit titles concise and understandable.
-- Do not invent files.
 
 Staged file inventory:
 {file_inventory}
@@ -12450,7 +12814,10 @@ Condensed staged diff:
 {summary}
 
 Additional context:
-{additional_context}`);
+{additional_context}
+
+Feedback on previous attempt (fix every item before responding):
+{previous_attempt_feedback}`);
 function isCommitSplitCommand(argv) {
     return Boolean(argv.split || argv.plan || argv.apply || argv._.includes('split'));
 }
@@ -12469,9 +12836,6 @@ function formatCommitSplitPlan(plan) {
     })
         .join('\n\n---\n\n');
 }
-function getStagedFileSet(changes) {
-    return new Set(changes.map((change) => change.filePath));
-}
 function getGroupFiles(group) {
     return group.files || [];
 }
@@ -12528,67 +12892,9 @@ function formatHunkInventory(inventory) {
         .join('\n');
 }
 function validatePlanForStagedFiles(plan, staged, hunkInventory) {
-    const stagedFiles = getStagedFileSet(staged);
-    const seen = new Set();
-    const seenHunks = new Set();
-    const unknown = [];
-    const duplicate = [];
-    const unknownHunks = [];
-    const duplicateHunks = [];
-    plan.groups.forEach((group) => {
-        getGroupFiles(group).forEach((file) => {
-            if (!stagedFiles.has(file)) {
-                unknown.push(file);
-                return;
-            }
-            if (seen.has(file)) {
-                duplicate.push(file);
-                return;
-            }
-            seen.add(file);
-        });
-        getGroupHunks(group).forEach((hunkId) => {
-            const hunk = hunkInventory?.byId.get(hunkId);
-            if (!hunk) {
-                unknownHunks.push(hunkId);
-                return;
-            }
-            if (seenHunks.has(hunkId)) {
-                duplicateHunks.push(hunkId);
-                return;
-            }
-            seenHunks.add(hunkId);
-        });
-    });
-    const hunkCoveredFiles = new Set([...seenHunks].map((hunkId) => hunkInventory?.byId.get(hunkId)?.filePath));
-    const mixedFiles = [...seen].filter((file) => hunkCoveredFiles.has(file));
-    const partiallyCoveredFiles = [...hunkCoveredFiles]
-        .filter((file) => Boolean(file))
-        .filter((file) => {
-        const fileHunks = hunkInventory?.byFile.get(file) || [];
-        return fileHunks.some((hunk) => !seenHunks.has(hunk.id));
-    });
-    const missing = [...stagedFiles].filter((file) => !seen.has(file) && !hunkCoveredFiles.has(file));
-    if (unknown.length ||
-        duplicate.length ||
-        unknownHunks.length ||
-        duplicateHunks.length ||
-        mixedFiles.length ||
-        partiallyCoveredFiles.length ||
-        missing.length) {
-        throw new Error([
-            unknown.length ? `unknown files: ${unknown.join(', ')}` : undefined,
-            duplicate.length ? `duplicate files: ${duplicate.join(', ')}` : undefined,
-            unknownHunks.length ? `unknown hunks: ${unknownHunks.join(', ')}` : undefined,
-            duplicateHunks.length ? `duplicate hunks: ${duplicateHunks.join(', ')}` : undefined,
-            mixedFiles.length ? `files assigned both as whole files and hunks: ${mixedFiles.join(', ')}` : undefined,
-            partiallyCoveredFiles.length
-                ? `files with only some hunks assigned: ${partiallyCoveredFiles.join(', ')}`
-                : undefined,
-            missing.length ? `missing files: ${missing.join(', ')}` : undefined,
-        ]
-            .filter(Boolean)
-            .join('; '));
+    const issues = getPlanValidationIssues(plan, staged, hunkInventory);
+    if (hasPlanValidationIssues(issues)) {
+        throw new Error(formatPlanValidationIssuesError(issues));
     }
 }
 function assertNoUnstagedOverlap(plan, changes, hunkInventory) {
@@ -12692,22 +12998,26 @@ async function handleCommitSplit({ argv, config, git, logger, tokenizer, llm, })
         .map((change) => `- ${change.filePath}: ${change.status} - ${change.summary}`)
         .join('\n');
     const hunkInventoryText = formatHunkInventory(hunkInventory);
-    const plan = await executeChainWithSchema(CommitSplitPlanSchema, llm, COMMIT_SPLIT_PROMPT, {
-        file_inventory: fileInventory,
-        hunk_inventory: hunkInventoryText,
-        summary,
-        additional_context: argv.additional || '',
-    }, {
+    const { plan } = await generateValidatedCommitSplitPlan({
+        llm,
+        prompt: COMMIT_SPLIT_PROMPT,
+        variables: {
+            file_inventory: fileInventory,
+            hunk_inventory: hunkInventoryText,
+            summary,
+            additional_context: argv.additional || '',
+        },
+        staged: changes.staged,
+        hunkInventory,
         logger,
         tokenizer,
         metadata: {
-            task: 'commit-split-plan',
             command: 'commit',
             provider: config.service.provider,
             model: String(config.service.model),
         },
+        maxAttempts: DEFAULT_MAX_PLAN_ATTEMPTS,
     });
-    validatePlanForStagedFiles(plan, changes.staged, hunkInventory);
     if (argv.apply) {
         return await applyCommitSplitPlan({
             plan,