@astrosheep/keiyaku 0.1.0

package/README.md

@@ -0,0 +1,72 @@
+# 🤝 Keiyaku
+
+**Keiyaku** is an MCP server designed for the **Architect-Minion workflow**. It enforces a strict, review-driven protocol for iterative coding tasks.
+
+Instead of messy, unstructured chat, Keiyaku turns every task into a formal "Keiyaku": a branch-based, multi-round journey with a clear beginning, a traced middle, and a definitive end.
+
+## 🚀 Why Keiyaku?
+
+- **Zero Mess**: Every task lives in its own `keiyaku/*` branch. Your main branch stays pristine.
+- **Traceable Logic**: Every iteration is documented in `KEIYAKU_TRACE.md`. You can literally see the AI's "learning curve" (or mistakes).
+- **Strict Guardrails**: No "Done" until you say so. No merging until the criteria are met.
+- **Human-in-the-Loop**: Designed for humans who actually want to review the code before it hits production.
+
+## 🔄 The Lifecycle
+
+The workflow is a simple, non-negotiable loop:
+
+1.  **`summon`**: Initiate the keiyaku. Creates a branch, locks the mission in `KEIYAKU.md`, and starts Round 1.
+2.  **`drive`** (N times): Review the work, give feedback, and launch the next round.
+3.  **`seal`**: The final verdict. `DONE` (merge & clean) or `DROP` (nuke the branch).
+
+## 🛠 Available Tools
+
+| Tool | Action | Description |
+| :--- | :--- | :--- |
+| **`summon`** | Start | Define the goal, constraints, and criteria. Starts the first round. |
+| **`drive`** | Iterate | Provide feedback based on the previous round's output. |
+| **`ask`** | Reason | Pure read-only analysis session. No code changes, just brain power. |
+| **`seal`** | Finish | Finalize the task. Requires a quality check (the "Oath"). |
+
+## 🎨 Flavor Your Workflow
+
+Bored with generic tool names? Keiyaku supports **Term Presets**. Change the vibe via the `KEIYAKU_TERM_PRESET` environment variable.
+
+- **`default`**: `summon` → `drive` → `seal` (Professional)
+- **`pokemon`**: `choose_you` → `command` → `capture` (Gotta code 'em all)
+- **`faye`**: `oi` → `neh` → `hora` (For those who like a little attitude)
+
+## 📦 Setup
+
+### 1. Install
+```bash
+npm install -g keiyaku
+```
+
+### 2. Configure MCP (Example: Claude Desktop)
+Add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "keiyaku": {
+      "command": "npx",
+      "args": ["-y", "keiyaku"],
+      "env": {
+        "KEIYAKU_TERM_PRESET": "faye" 
+      }
+    }
+  }
+}
+```
+
+## 📜 Protocol Files
+
+When a keiyaku is active, two files are maintained in your repo:
+- `KEIYAKU.md`: The immutable "Constitution" of the task.
+- `KEIYAKU_TRACE.md`: The history of every round, feedback, and result.
+
+*Note: These files are automatically cleaned up (or committed) when you `seal` the keiyaku.*
+
+---
+"Keep your branches clean and your minions in line." — Faye

package/build/codex.js

@@ -0,0 +1,2 @@
+// Backward-compatible facade. New code should import from ./subagent-exec/index.js.
+export { getSubagentNames, resolveSubagentConfig, runSubagentExec, isSubagentExecError as isCodexExecError, SubagentExecError as CodexExecError, } from "./subagent-exec/index.js";

package/build/constants.js

@@ -0,0 +1,3 @@
+export const KEIYAKU_FILE = "KEIYAKU.md";
+export const TRACE_FILE = "KEIYAKU_TRACE.md";
+export const ROUND_SUBAGENTS = ["servant-tier-B", "servant-tier-A", "servant-tier-S"];

package/build/debug-log.js

@@ -0,0 +1,36 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+let writeQueue = Promise.resolve();
+function resolveLogPath(cwd) {
+    const raw = process.env.KEIYAKU_DEBUG_LOG_PATH?.trim();
+    if (!raw)
+        return null;
+    if (path.isAbsolute(raw))
+        return raw;
+    return path.resolve(cwd || process.cwd(), raw);
+}
+function formatLine(message, section) {
+    const timestamp = new Date().toISOString();
+    const sec = section?.trim() ? ` [${section.trim()}]` : "";
+    return `[${timestamp}] [pid:${process.pid}]${sec} ${message}\n`;
+}
+export function appendDebugLog(message, options = {}) {
+    const logPath = resolveLogPath(options.cwd);
+    if (!logPath)
+        return;
+    const line = formatLine(message, options.section);
+    writeQueue = writeQueue
+        .then(async () => {
+        await fs.mkdir(path.dirname(logPath), { recursive: true });
+        await fs.appendFile(logPath, line, "utf-8");
+    })
+        .catch(() => {
+        // Best-effort logging should never break runtime behavior.
+    });
+}
+export function appendDebugBlock(title, content, options = {}) {
+    const text = content.trim();
+    if (!text)
+        return;
+    appendDebugLog(`${title}\n${text}`, options);
+}

package/build/errors.js

@@ -0,0 +1,114 @@
+import { ROUND_SUBAGENTS } from "./constants.js";
+import { resolveTermPreset } from "./term-presets.js";
+function unknownSubagentHint() {
+    const names = ROUND_SUBAGENTS.join(", ");
+    const { identity } = resolveTermPreset();
+    return `Unknown ${identity.toLowerCase()} name. Configured ${identity.toLowerCase()}s: ${names}. Choose one via tool input 'subagentName' or env 'KEIYAKU_SUBAGENT_NAME_OVERRIDE'.`;
+}
+export class FlowError extends Error {
+    code;
+    constructor(code, message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "FlowError";
+        this.code = code;
+    }
+}
+export function isFlowError(err) {
+    return err instanceof FlowError;
+}
+export function asMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export function wrapFlowError(action, err) {
+    if (err instanceof Error && err.name === "AbortError") {
+        return err;
+    }
+    if (isFlowError(err)) {
+        return new FlowError(err.code, `${action} failed: ${err.message}`, err);
+    }
+    return new Error(`${action} failed: ${asMessage(err)}`);
+}
+export function pickHintFromError(err, message) {
+    if (isFlowError(err)) {
+        switch (err.code) {
+            case "NOT_GIT_REPO":
+                return "The provided `cwd` is not a git repository.";
+            case "ACTIVE_KEIYAKU_EXISTS":
+                return "An active keiyaku branch already exists in this repository.";
+            case "EXISTING_KEIYAKU_BRANCH_FOUND":
+                return "At least one local `keiyaku/*` branch already exists in this repository.";
+            case "EMPTY_PARAM":
+                return "One or more required parameters are empty.";
+            case "DIRTY_WORKTREE":
+                return "The working tree has uncommitted changes.";
+            case "NOT_ACTIVE_KEIYAKU_BRANCH":
+                return "Current branch is not an active keiyaku branch (`keiyaku/*`).";
+            case "MISSING_KEIYAKU_BASE":
+                return "Current keiyaku branch is missing `keiyakuBase` metadata.";
+            case "MISSING_PROTOCOL_FILES":
+                return "Required protocol files are missing (`KEIYAKU.md` or `KEIYAKU_TRACE.md`).";
+            case "DONE_MERGE_CONFLICT":
+                return "DONE encountered a git merge conflict.";
+            case "JUDGMENT_QUALITY_GATE_FAILED":
+                return "DONE requires metPrecise/metMinimal/metIsolated/metIdiomatic/metCohesive all set to true.";
+            case "JUDGMENT_OATH_MISMATCH":
+                return err.message;
+            case "SUBAGENT_DID_NOT_ADVANCE_ROUND":
+                return "Subagent run did not append the expected new round in `KEIYAKU_TRACE.md`.";
+            case "INVALID_BRANCH_TITLE":
+                return "Title cannot be converted to a valid branch token for `keiyaku/<title>`.";
+            case "UNKNOWN_SUBAGENT":
+                return unknownSubagentHint();
+            default:
+                return "Review the error details, fix the issue, and retry.";
+        }
+    }
+    // Fallback for untyped runtime errors.
+    if (message.includes("is not a git repository")) {
+        return "The provided `cwd` is not a git repository.";
+    }
+    if (message.includes("active keiyaku already exists")) {
+        return "An active keiyaku branch already exists in this repository.";
+    }
+    if (message.includes("existing keiyaku branch found")) {
+        return "At least one local `keiyaku/*` branch already exists in this repository.";
+    }
+    if (message.includes("parameter") && message.includes("cannot be empty")) {
+        return "One or more required parameters are empty.";
+    }
+    if (message.includes("working tree has uncommitted changes")) {
+        return "The working tree has uncommitted changes.";
+    }
+    if (message.includes("current branch is not an active keiyaku branch")) {
+        return "Current branch is not an active keiyaku branch (`keiyaku/*`).";
+    }
+    if (message.includes("is missing base metadata")) {
+        return "Current keiyaku branch is missing `keiyakuBase` metadata.";
+    }
+    if (message.includes("missing protocol files")) {
+        return "Required protocol files are missing (`KEIYAKU.md` or `KEIYAKU_TRACE.md`).";
+    }
+    if (message.includes("DONE merge conflict")) {
+        return "DONE encountered a git merge conflict.";
+    }
+    if (message.includes("requires metPrecise/metMinimal/metIsolated/metIdiomatic/metCohesive all set to true")) {
+        return "DONE requires metPrecise/metMinimal/metIsolated/metIdiomatic/metCohesive all set to true.";
+    }
+    if (message.includes("requires the sacred oath to exactly equal") ||
+        message.includes("requires oath to exactly match configured value") ||
+        message.includes("requires oath to match configured value. If template contains") ||
+        message.includes("To declare DONE, you must solemnly swear the sacred oath.") ||
+        message.includes("To declare DONE, oath mismatch.")) {
+        return message;
+    }
+    if (message.includes("subagent did not advance round") || message.includes("did not append KEIYAKU_TRACE")) {
+        return "Subagent run did not append the expected new round in `KEIYAKU_TRACE.md`.";
+    }
+    if (message.includes("cannot be converted to a valid branch name")) {
+        return "Title cannot be converted to a valid branch token for `keiyaku/<title>`.";
+    }
+    if (message.includes("Unknown subagent")) {
+        return unknownSubagentHint();
+    }
+    return "Review the error details, fix the issue, and retry.";
+}

package/build/git.js

@@ -0,0 +1,462 @@
+import { simpleGit } from "simple-git";
+import { appendDebugBlock } from "./debug-log.js";
+const DEFAULT_MAX_LINES_PER_FILE = 80;
+const DEFAULT_MAX_TOTAL_LINES = 500;
+const DEFAULT_GIT_TIMEOUT_MS = 15 * 1000;
+const DIFF_EXCLUDES = [":(exclude)KEIYAKU.md", ":(exclude)KEIYAKU_TRACE.md"];
+// Diff preview limits (no env/config knobs on purpose).
+const DIFF_PREVIEW_MAX_FILES = 12;
+const DIFF_PREVIEW_MAX_HUNKS_PER_FILE = 2;
+const DIFF_PREVIEW_MAX_LINES_PER_HUNK = 40;
+const DIFF_PREVIEW_MAX_PRELUDE_LINES = 30;
+function readPositiveIntEnv(name, fallback) {
+    const raw = process.env[name]?.trim();
+    if (!raw)
+        return fallback;
+    const value = Number.parseInt(raw, 10);
+    return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+function readBooleanEnv(name, fallback) {
+    const raw = process.env[name]?.trim().toLowerCase();
+    if (!raw)
+        return fallback;
+    if (raw === "1" || raw === "true" || raw === "yes" || raw === "on")
+        return true;
+    if (raw === "0" || raw === "false" || raw === "no" || raw === "off")
+        return false;
+    return fallback;
+}
+function compactText(input, maxChars = 4000) {
+    const text = input.trim();
+    if (!text)
+        return "";
+    if (text.length <= maxChars)
+        return text;
+    const marker = `\n...[truncated ${text.length - maxChars} chars]...\n`;
+    const side = Math.floor((maxChars - marker.length) / 2);
+    return `${text.slice(0, side)}${marker}${text.slice(text.length - side)}`;
+}
+function wrapGitError(commandLabel, err, cwd) {
+    const source = (err ?? {});
+    const message = source.message ?? String(err);
+    const stderr = compactText(source.stderr ?? source.stdErr ?? "");
+    const stdout = compactText(source.stdout ?? source.stdOut ?? "");
+    let detailedMessage = `[git ${commandLabel}] ${message}`;
+    if (stderr)
+        detailedMessage += `\n\n--- GIT STDERR ---\n${stderr}\n------------------`;
+    if (stdout)
+        detailedMessage += `\n\n--- GIT STDOUT ---\n${stdout}\n------------------`;
+    if (stderr || stdout) {
+        appendDebugBlock(`git ${commandLabel} failure details`, `${detailedMessage}`, { cwd, section: "git-error" });
+    }
+    const wrapped = new Error(detailedMessage, err === undefined ? undefined : { cause: err });
+    if (source.git !== undefined) {
+        Object.assign(wrapped, { git: source.git });
+    }
+    return wrapped;
+}
+function createGit(cwd) {
+    const timeoutMs = readPositiveIntEnv("KEIYAKU_GIT_TIMEOUT_MS", DEFAULT_GIT_TIMEOUT_MS);
+    const git = simpleGit(cwd, {
+        timeout: { block: timeoutMs, stdErr: true, stdOut: true },
+    });
+    git.env("GIT_TERMINAL_PROMPT", "0");
+    git.env("GCM_INTERACTIVE", "Never");
+    git.env("GIT_ASKPASS", "false");
+    git.env("SSH_ASKPASS", "false");
+    git.env("GIT_EDITOR", "true");
+    git.env("GIT_MERGE_AUTOEDIT", "no");
+    return git;
+}
+export async function isGitRepo(cwd) {
+    const git = createGit(cwd);
+    try {
+        return await git.checkIsRepo();
+    }
+    catch (err) {
+        throw wrapGitError("check-is-repo", err, cwd);
+    }
+}
+export async function getCurrentBranch(cwd) {
+    const git = createGit(cwd);
+    let status;
+    try {
+        status = await git.status();
+    }
+    catch (err) {
+        throw wrapGitError("status", err, cwd);
+    }
+    if (!status.current) {
+        throw new Error("Detached HEAD or no branch found");
+    }
+    return status.current;
+}
+export async function getActiveKeiyakuBranch(cwd) {
+    const current = await getCurrentBranch(cwd);
+    return current.startsWith("keiyaku/") ? current : null;
+}
+export async function listLocalKeiyakuBranches(cwd) {
+    const git = createGit(cwd);
+    let branches;
+    try {
+        branches = await git.branchLocal();
+    }
+    catch (err) {
+        throw wrapGitError("branch --list", err, cwd);
+    }
+    return branches.all.filter((name) => name.startsWith("keiyaku/"));
+}
+export async function createAndCheckoutBranch(cwd, branchName) {
+    const git = createGit(cwd);
+    try {
+        await git.checkoutLocalBranch(branchName);
+    }
+    catch (err) {
+        throw wrapGitError(`checkout -b ${branchName}`, err, cwd);
+    }
+}
+export async function checkoutBranch(cwd, branchName) {
+    const git = createGit(cwd);
+    try {
+        await git.checkout(branchName);
+    }
+    catch (err) {
+        throw wrapGitError(`checkout ${branchName}`, err, cwd);
+    }
+}
+export async function deleteBranch(cwd, branchName, force = false) {
+    const git = createGit(cwd);
+    try {
+        await git.deleteLocalBranch(branchName, force);
+    }
+    catch (err) {
+        throw wrapGitError(`branch -d${force ? " -D" : ""} ${branchName}`, err, cwd);
+    }
+}
+export async function addFiles(cwd, files) {
+    const git = createGit(cwd);
+    try {
+        await git.add(files);
+    }
+    catch (err) {
+        throw wrapGitError("add", err, cwd);
+    }
+}
+export async function commit(cwd, message) {
+    const git = createGit(cwd);
+    const skipVerify = readBooleanEnv("KEIYAKU_GIT_NO_VERIFY", true);
+    const noGpgSign = readBooleanEnv("KEIYAKU_GIT_NO_GPG_SIGN", true);
+    const args = ["commit", "-m", message];
+    if (skipVerify)
+        args.push("--no-verify");
+    if (noGpgSign)
+        args.push("--no-gpg-sign");
+    try {
+        await git.raw(args);
+    }
+    catch (err) {
+        throw wrapGitError(args.join(" "), err, cwd);
+    }
+}
+export async function merge(cwd, branchName, message) {
+    const git = createGit(cwd);
+    const skipVerify = readBooleanEnv("KEIYAKU_GIT_NO_VERIFY", true);
+    const noGpgSign = readBooleanEnv("KEIYAKU_GIT_NO_GPG_SIGN", true);
+    const options = [branchName, "--no-ff", "--no-edit", "-m", message];
+    if (skipVerify)
+        options.push("--no-verify");
+    if (noGpgSign)
+        options.push("--no-gpg-sign");
+    try {
+        await git.merge(options);
+    }
+    catch (err) {
+        throw wrapGitError(`merge ${options.join(" ")}`, err, cwd);
+    }
+}
+export async function hasLocalBranch(cwd, branchName) {
+    const git = createGit(cwd);
+    let branches;
+    try {
+        branches = await git.branchLocal();
+    }
+    catch (err) {
+        throw wrapGitError("branch --list", err, cwd);
+    }
+    return branches.all.includes(branchName);
+}
+export async function getDirtyPaths(cwd) {
+    const git = createGit(cwd);
+    let status;
+    try {
+        status = await git.status();
+    }
+    catch (err) {
+        throw wrapGitError("status --porcelain", err, cwd);
+    }
+    const paths = status.files.map((f) => f.path);
+    return Array.from(new Set(paths));
+}
+export async function assertValidBranchName(cwd, branchName) {
+    const git = createGit(cwd);
+    try {
+        await git.raw(["check-ref-format", "--branch", branchName]);
+    }
+    catch (err) {
+        throw wrapGitError(`check-ref-format --branch ${branchName}`, err, cwd);
+    }
+}
+function branchBaseKey(branchName) {
+    return `branch.${branchName}.keiyakuBase`;
+}
+export async function setKeiyakuBase(cwd, branchName, baseBranch) {
+    const git = createGit(cwd);
+    try {
+        await git.raw(["config", branchBaseKey(branchName), baseBranch]);
+    }
+    catch (err) {
+        throw wrapGitError(`config ${branchBaseKey(branchName)} ${baseBranch}`, err, cwd);
+    }
+}
+export async function getKeiyakuBase(cwd, branchName) {
+    const git = createGit(cwd);
+    try {
+        const value = await git.raw(["config", "--get", branchBaseKey(branchName)]);
+        return value.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function clearKeiyakuBase(cwd, branchName) {
+    const git = createGit(cwd);
+    try {
+        await git.raw(["config", "--unset", branchBaseKey(branchName)]);
+    }
+    catch {
+        // Branch config may already be absent.
+    }
+}
+function buildDiffPathspec(baseBranch) {
+    return [`${baseBranch}...HEAD`, "--", ".", ...DIFF_EXCLUDES];
+}
+function parseNumStat(content) {
+    const rows = [];
+    for (const line of content.split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        const [addRaw, delRaw, ...pathParts] = line.split("\t");
+        const filePath = pathParts.join("\t").trim();
+        if (!filePath)
+            continue;
+        const binary = addRaw === "-" || delRaw === "-";
+        rows.push({
+            path: filePath,
+            additions: binary ? 0 : Number.parseInt(addRaw, 10) || 0,
+            deletions: binary ? 0 : Number.parseInt(delRaw, 10) || 0,
+            binary,
+        });
+    }
+    return rows;
+}
+function parseNameStatus(content) {
+    const map = new Map();
+    for (const line of content.split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        const parts = line.split("\t");
+        const statusRaw = (parts[0] ?? "").trim();
+        if (!statusRaw)
+            continue;
+        if ((statusRaw.startsWith("R") || statusRaw.startsWith("C")) && parts.length >= 3) {
+            const scoreRaw = statusRaw.slice(1);
+            const score = Number.parseInt(scoreRaw, 10);
+            const oldPath = (parts[1] ?? "").trim();
+            const path = (parts[2] ?? "").trim();
+            if (!path)
+                continue;
+            const status = statusRaw[0] === "R" ? "R" : "C";
+            map.set(path, { status, score: Number.isFinite(score) ? score : 0, oldPath, path });
+            continue;
+        }
+        const path = (parts[1] ?? "").trim();
+        if (!path)
+            continue;
+        // Git can emit single-letter statuses, possibly in combinations; we keep just the first.
+        const status = statusRaw[0];
+        map.set(path, { status, path });
+    }
+    return map;
+}
+function splitDiffByFile(content) {
+    const sections = [];
+    let current = [];
+    for (const line of content.split(/\r?\n/)) {
+        if (line.startsWith("diff --git ")) {
+            if (current.length > 0)
+                sections.push(current);
+            current = [line];
+            continue;
+        }
+        if (current.length > 0)
+            current.push(line);
+    }
+    if (current.length > 0)
+        sections.push(current);
+    return sections;
+}
+export async function getKeiyakuDiffStats(cwd, baseBranch) {
+    const git = createGit(cwd);
+    const pathspec = buildDiffPathspec(baseBranch);
+    let rawNumStat;
+    try {
+        rawNumStat = await git.raw(["diff", "--numstat", ...pathspec]);
+    }
+    catch (err) {
+        throw wrapGitError(`diff --numstat ${baseBranch}...HEAD`, err, cwd);
+    }
+    const rows = parseNumStat(rawNumStat);
+    return {
+        filesChanged: rows.length,
+        insertions: rows.reduce((sum, row) => sum + row.additions, 0),
+        deletions: rows.reduce((sum, row) => sum + row.deletions, 0),
+    };
+}
+function parseDiffPathFromHeader(diffGitLine) {
+    // Format: diff --git a/<path> b/<path>
+    const parts = diffGitLine.split(" ");
+    const bPart = parts[3] ?? "";
+    if (!bPart.startsWith("b/"))
+        return null;
+    return bPart.slice(2);
+}
+function buildPatchPreview(section) {
+    // Keep a small, representative prelude (diff header, index, ---/+++), then first N hunks.
+    const firstHunkIdx = section.findIndex((l) => l.startsWith("@@ "));
+    const prelude = firstHunkIdx === -1 ? section : section.slice(0, firstHunkIdx).slice(0, DIFF_PREVIEW_MAX_PRELUDE_LINES);
+    if (firstHunkIdx === -1) {
+        const truncated = section.length > DIFF_PREVIEW_MAX_PRELUDE_LINES;
+        const lines = truncated
+            ? [...prelude, `... [truncated ${section.length - prelude.length} prelude line(s)]`]
+            : prelude;
+        return { patch: lines.join("\n"), truncated };
+    }
+    const hunks = [];
+    let current = [];
+    for (const line of section.slice(firstHunkIdx)) {
+        if (line.startsWith("@@ ")) {
+            if (current.length > 0)
+                hunks.push(current);
+            current = [line];
+            continue;
+        }
+        if (current.length > 0)
+            current.push(line);
+    }
+    if (current.length > 0)
+        hunks.push(current);
+    let truncated = false;
+    const shownHunks = hunks.slice(0, DIFF_PREVIEW_MAX_HUNKS_PER_FILE).map((hunk) => {
+        if (hunk.length <= DIFF_PREVIEW_MAX_LINES_PER_HUNK)
+            return hunk;
+        truncated = true;
+        return [
+            ...hunk.slice(0, DIFF_PREVIEW_MAX_LINES_PER_HUNK),
+            `... [truncated ${hunk.length - DIFF_PREVIEW_MAX_LINES_PER_HUNK} line(s) in this hunk]`,
+        ];
+    });
+    if (hunks.length > DIFF_PREVIEW_MAX_HUNKS_PER_FILE) {
+        truncated = true;
+    }
+    const lines = [
+        ...prelude,
+        ...shownHunks.flat(),
+        ...(hunks.length > DIFF_PREVIEW_MAX_HUNKS_PER_FILE
+            ? [`... [omitted ${hunks.length - DIFF_PREVIEW_MAX_HUNKS_PER_FILE} hunk(s)]`]
+            : []),
+    ];
+    return { patch: lines.join("\n"), truncated };
+}
+/**
+ * Gets a compact, structured diff preview for quick review.
+ * - Always includes full stats for the whole range.
+ * - Includes patch previews for the top churn files only (hunk-based truncation).
+ */
+export async function getKeiyakuDiff(cwd, baseBranch) {
+    const git = createGit(cwd);
+    const pathspec = buildDiffPathspec(baseBranch);
+    const range = `${baseBranch}...HEAD`;
+    let rawNumStat;
+    try {
+        rawNumStat = await git.raw(["diff", "--numstat", ...pathspec]);
+    }
+    catch (err) {
+        throw wrapGitError(`diff --numstat ${range}`, err);
+    }
+    const rows = parseNumStat(rawNumStat);
+    const stats = {
+        filesChanged: rows.length,
+        insertions: rows.reduce((sum, row) => sum + row.additions, 0),
+        deletions: rows.reduce((sum, row) => sum + row.deletions, 0),
+    };
+    let rawNameStatus = "";
+    try {
+        rawNameStatus = await git.raw(["diff", "--name-status", ...pathspec]);
+    }
+    catch (err) {
+        throw wrapGitError(`diff --name-status ${range}`, err);
+    }
+    const statusByPath = parseNameStatus(rawNameStatus);
+    const sorted = [...rows].sort((a, b) => b.additions + b.deletions - (a.additions + a.deletions));
+    const selected = sorted.slice(0, DIFF_PREVIEW_MAX_FILES);
+    const omittedFileCount = Math.max(0, rows.length - selected.length);
+    const selectedPaths = selected.map((r) => r.path);
+    let rawPatch = "";
+    if (selectedPaths.length > 0) {
+        try {
+            rawPatch = await git.raw([
+                "diff",
+                "--no-color",
+                "--no-ext-diff",
+                "--unified=3",
+                range,
+                "--",
+                ...selectedPaths,
+                ...DIFF_EXCLUDES,
+            ]);
+        }
+        catch (err) {
+            throw wrapGitError(`diff --no-color --no-ext-diff --unified=3 ${range} -- <top files>`, err);
+        }
+    }
+    const sections = rawPatch ? splitDiffByFile(rawPatch) : [];
+    const patchByPath = new Map();
+    for (const section of sections) {
+        const path = parseDiffPathFromHeader(section[0] ?? "");
+        if (!path)
+            continue;
+        patchByPath.set(path, buildPatchPreview(section));
+    }
+    const files = selected.map((row) => {
+        const status = statusByPath.get(row.path);
+        const patch = patchByPath.get(row.path)?.patch ?? "";
+        const truncated = patchByPath.get(row.path)?.truncated ?? false;
+        return {
+            path: row.path,
+            status: status?.status ?? "M",
+            oldPath: status && (status.status === "R" || status.status === "C") ? status.oldPath : undefined,
+            additions: row.additions,
+            deletions: row.deletions,
+            binary: row.binary,
+            patch,
+            truncated,
+        };
+    });
+    return {
+        range,
+        excludes: DIFF_EXCLUDES,
+        stats,
+        files,
+        omittedFileCount,
+    };
+}