@astrosheep/keiyaku 0.1.17 → 0.1.19

package/build/common/errors.js

@@ -70,57 +70,17 @@ function hintForFlowCode(code, message) {
             return `\`${preset.tools.start.name}\` requires a clean slate. Remove existing \`KEIYAKU.md\` before starting.`;
         case "DRAFT_FILE_EXISTS":
             return `Existing \`KEIYAKU.draft.md\` detected. Use it via \`from_file\` or delete it before starting.`;
+        case "DETACHED_HEAD":
+            return "Repository is in detached HEAD state. Switch to a branch and retry.";
+        case "INVALID_CLOSE_PETITION":
+            return "Invalid close petition. Use `CLAIM` or `FORFEIT`.";
+        case "INTERNAL_STATE":
+            return message;
     }
 }
-const MESSAGE_HINT_PATTERNS = [
-    { code: "NOT_GIT_REPO", patterns: ["is not a git repository"] },
-    { code: "ACTIVE_KEIYAKU_EXISTS", patterns: ["active keiyaku already exists"] },
-    { code: "EXISTING_KEIYAKU_BRANCH_FOUND", patterns: ["existing keiyaku branch found"] },
-    { code: "EMPTY_PARAM", patterns: ["cannot be empty"] },
-    { code: "DIRTY_WORKTREE", patterns: ["working tree has uncommitted changes"] },
-    { code: "NOT_ACTIVE_KEIYAKU_BRANCH", patterns: ["current branch is not an active keiyaku branch"] },
-    { code: "MISSING_KEIYAKU_BASE", patterns: ["is missing base metadata"] },
-    { code: "MISSING_PROTOCOL_FILES", patterns: ["missing protocol files"] },
-    { code: "DONE_MERGE_CONFLICT", patterns: ["DONE merge conflict"] },
-    { code: "CLOSE_QUALITY_GATE_FAILED", patterns: ["God's Wrath: CLAIM denied"] },
-    {
-        code: "OATH_MISMATCH",
-        patterns: [
-            "requires the sacred oath to exactly equal",
-            "requires oath to exactly match configured value",
-            "requires oath to match configured value. If template contains",
-            "To declare DONE, you must solemnly swear the sacred oath.",
-            "To declare DONE, oath mismatch.",
-            "Oath mismatch.",
-        ],
-    },
-    {
-        code: "SUBAGENT_DID_NOT_ADVANCE_ROUND",
-        patterns: ["subagent did not advance round", "did not append KEIYAKU_TRACE"],
-    },
-    { code: "ROUND_SUBAGENT_FAILED", patterns: ["failed during subagent execution"] },
-    { code: "INVALID_BRANCH_TITLE", patterns: ["cannot be converted to a valid branch name"] },
-    { code: "UNKNOWN_SUBAGENT", patterns: ["Unknown subagent"] },
-    { code: "FROM_FILE_NOT_FOUND", patterns: ["from_file path does not exist"] },
-    { code: "INVALID_KEIYAKU_DRAFT", patterns: ["invalid keiyaku draft"] },
-    { code: "KEIYAKU_FILE_EXISTS", patterns: ["pre-flight failed: KEIYAKU.md already exists"] },
-    { code: "DRAFT_FILE_EXISTS", patterns: ["pre-flight failed: KEIYAKU.draft.md exists but from_file does not target it"] },
-];
-function inferFlowCodeFromMessage(message) {
-    for (const entry of MESSAGE_HINT_PATTERNS) {
-        if (entry.patterns.some((pattern) => message.includes(pattern))) {
-            return entry.code;
-        }
-    }
-    return null;
-}
-export function pickHintFromError(err, message) {
+export function pickHintFromError(err) {
     if (isFlowError(err)) {
         return hintForFlowCode(err.code, err.message);
     }
-    const inferredCode = inferFlowCodeFromMessage(message);
-    if (inferredCode) {
-        return hintForFlowCode(inferredCode, message);
-    }
     return "Review the error details, fix the issue, and retry.";
 }

package/build/config/term-presets.js

@@ -57,7 +57,7 @@ export const DEFAULT_PRESET = {
             title: 'Sign Keiyaku',
             description: 'Initialize a Keiyaku (Contract). Bind a Servant to a dedicated workspace (branch).\nYou are the Architect; they are the Instrument. Define the Goal and Scope clearly.\nThe contract isolates their existence until the objective is met.\nCall ONCE to seal the bond.\n\nFlow: ${start} → [${drive} x N] → ${close}',
             args: {
-                from_file: "Optional markdown draft path. Loads `# title` + required sections from file (relative to cwd unless absolute).",
+                from_file: "Optional markdown draft path. Loads `# title` + required sections from file (relative to cwd unless absolute). Note: this file is auto-ignored by dirty-tree checks.",
                 title: 'Required unless provided via `from_file`. A concise codename for this hunt.',
                 goal: 'Required unless provided via `from_file`. The Kill Condition for this mission.',
                 directive: 'Optional First Step. Overrides `## Directive` from `from_file` when both are provided.',
@@ -99,17 +99,20 @@ export const DEFAULT_PRESET = {
                 'If there is a bug, **YOU** put it there.\n' +
                 'If it is messy, **YOU** left it there.\n\n' +
                 'Stand by your work. If uncertain, return to ${drive}. Premature claims are not forgiven.\n\n' +
+                'Input rules:\n' +
+                '- CLAIM: fill criteriaChecks, constraintsChecks, all five scores, and oath.\n' +
+                '- FORFEIT: only petition is required; the other fields can be left empty.\n\n' +
                 'Flow: ${start} → [${drive} x N] → ${close}',
             args: {
                 petition: 'REQUIRED. CLAIM declares fulfillment; FORFEIT concedes failure.\nREQUIRES AN ACTIVE KEIYAKU (started via ${start}).\nIf any score wavers, do not claim—return to ${drive}.',
-                criteriaChecks: 'REQUIRED. For CLAIM: evidence that each criterion is met. For FORFEIT: honest account of what remains unfinished.',
-                constraintsChecks: 'REQUIRED. For CLAIM: evidence that each constraint stayed compliant. For FORFEIT: list known violations or unresolved risk.',
-                score_precise: 'REQUIRED (0-10). Architectural placement. 10 = exact layer, exact boundary, zero misplacement.',
-                score_minimal: 'REQUIRED (0-10). Economy of change. 10 = no avoidable lines, no speculative edits, no hidden bloat.',
-                score_isolated: 'REQUIRED (0-10). Surgical containment. 10 = zero unrelated files, zero opportunistic cleanup, zero collateral.',
-                score_idiomatic: 'REQUIRED (0-10). Native fluency. 10 = naming, structure, style indistinguishable from the codebase.',
-                score_cohesive: 'REQUIRED (0-10). Single responsibility. 10 = each unit does one thing, boundaries intact.',
-                oath: 'Required for CLAIM. Your binding word. The Contract holds you to it.\nVerbatim: ${oath_text}',
+                criteriaChecks: 'Required for CLAIM. Evidence that each criterion is met. For FORFEIT, optional (can be left empty).',
+                constraintsChecks: 'Required for CLAIM. Evidence that each constraint stayed compliant. For FORFEIT, optional (can be left empty).',
+                score_precise: 'Required for CLAIM (0-10). Architectural placement. 10 = exact layer, exact boundary, zero misplacement. For FORFEIT, optional.',
+                score_minimal: 'Required for CLAIM (0-10). Economy of change. 10 = no avoidable lines, no speculative edits, no hidden bloat. For FORFEIT, optional.',
+                score_isolated: 'Required for CLAIM (0-10). Surgical containment. 10 = zero unrelated files, zero opportunistic cleanup, zero collateral. For FORFEIT, optional.',
+                score_idiomatic: 'Required for CLAIM (0-10). Native fluency. 10 = naming, structure, style indistinguishable from the codebase. For FORFEIT, optional.',
+                score_cohesive: 'Required for CLAIM (0-10). Single responsibility. 10 = each unit does one thing, boundaries intact. For FORFEIT, optional.',
+                oath: 'Required for CLAIM. Your binding word. The Contract holds you to it. For FORFEIT, optional.\nVerbatim: ${oath_text}',
                 cwd: "Optional repository path. Defaults to the server's current working directory.",
             },
         },
@@ -159,7 +162,7 @@ export const POCKET_PRESET = {
             title: 'I Choose You!',
             description: 'Initialize the Battle Phase. Send a Critter (Servant) into a dedicated Arena (branch).\nYou are the Trainer; they are the Fighter. Define the Victory Condition (Goal) clearly.\nThe battle continues in this Arena until the Badge is won.\nCall ONCE to start the encounter.\n\nFlow: ${start} → [${drive} x N] → ${close}',
             args: {
-                from_file: 'Optional battle plan markdown path with title + sections.',
+                from_file: 'Optional battle plan markdown path with title + sections. This file is auto-ignored by dirty-tree checks.',
                 title: 'Required unless provided via `from_file`. Battle card title for this encounter.',
                 goal: 'Required unless provided via `from_file`. Victory condition for this battle.',
                 directive: 'Optional Turn 1 strategy (overrides draft directive).',
@@ -198,14 +201,14 @@ export const POCKET_PRESET = {
             description: 'Attempt Capture. Present the weakened target for League Inspection.\nWARNING: The League (System) checks every Badge. If you attempt to `CLAIM` with fainted code, Disqualification (FORFEIT) is immediate.\nOnly throw the Ball when the target is 100% ready.\n\nFlow: ${start} → [${drive} x N] → ${close}',
             args: {
                 petition: 'REQUIRED. CLAIM seeks Badge; FORFEIT forfeits the match.\nREQUIRES AN ACTIVE BATTLE (started via ${start}).\nIf stats are low, continue with ${drive}.',
-                criteriaChecks: 'REQUIRED. Badge-by-badge proof for CLAIM, or reason for Forfeit.',
-                constraintsChecks: 'REQUIRED. Rule-by-rule proof that constraints were respected, or known breaks when forfeiting.',
-                score_precise: 'REQUIRED score (0-10). 10 means a Critical Hit: exact layer, exact target, zero meaningful misplacement.',
-                score_minimal: 'REQUIRED score (0-10). 10 means Max Efficiency: no wasted PP, no extra motion.',
-                score_isolated: 'REQUIRED score (0-10). 10 means 1v1 Focus: zero side-quests, zero unrelated damage.',
-                score_idiomatic: "REQUIRED score (0-10). 10 means STAB (Same Type Attack Bonus): perfectly matches the codebase style.",
-                score_cohesive: 'REQUIRED score (0-10). 10 means Team Synergy: action serves one purpose with clean boundaries.',
-                oath: "Trainer's Honor Code. Required for CLAIM. Verbatim: ${oath_text}",
+                criteriaChecks: 'Required for CLAIM. Badge-by-badge proof. For FORFEIT, optional (can be left empty).',
+                constraintsChecks: 'Required for CLAIM. Rule-by-rule proof that constraints were respected. For FORFEIT, optional (can be left empty).',
+                score_precise: 'Required for CLAIM score (0-10). 10 means a Critical Hit: exact layer, exact target, zero meaningful misplacement. For FORFEIT, optional.',
+                score_minimal: 'Required for CLAIM score (0-10). 10 means Max Efficiency: no wasted PP, no extra motion. For FORFEIT, optional.',
+                score_isolated: 'Required for CLAIM score (0-10). 10 means 1v1 Focus: zero side-quests, zero unrelated damage. For FORFEIT, optional.',
+                score_idiomatic: "Required for CLAIM score (0-10). 10 means STAB (Same Type Attack Bonus): perfectly matches the codebase style. For FORFEIT, optional.",
+                score_cohesive: 'Required for CLAIM score (0-10). 10 means Team Synergy: action serves one purpose with clean boundaries. For FORFEIT, optional.',
+                oath: "Trainer's Honor Code. Required for CLAIM. For FORFEIT, optional. Verbatim: ${oath_text}",
                 cwd: 'Optional battlefield path (repository root). Defaults to current arena.',
             },
         },
@@ -255,7 +258,7 @@ export const MISCHIEF_PRESET = {
             title: 'Oi!',
             description: "Initiate Grand Scheme. Summon a Minion to the Lair (branch).\nYou are the Mastermind; they are the Henchman. Define the Conquest (Goal) with dominance.\nThe minion is bound to this Lair until the plot is realized.\nCall ONCE to start the machine.\n\nFlow: ${start} → [${drive} x N] → ${close}",
             args: {
-                from_file: 'Optional scheme markdown path with title + sectioned objectives.',
+                from_file: 'Optional scheme markdown path with title + sectioned objectives. This file is auto-ignored by dirty-tree checks.',
                 title: 'Required unless provided via `from_file`. Operation codename.',
                 goal: 'Required unless provided via `from_file`. Conquest objective and end-state.',
                 directive: 'Optional first-order command (overrides draft directive).',
@@ -294,14 +297,14 @@ export const MISCHIEF_PRESET = {
             description: 'The Final Reveal. Present your Masterpiece to the Dark Council (System).\nWARNING: The Council destroys failure. If you `CLAIM` with weak plans, you will be eaten (FORFEIT).\nOnly throw the switch when the Doomsday Device is 100% operational.\n\nFlow: ${start} → [${drive} x N] → ${close}',
             args: {
                 petition: 'REQUIRED. CLAIM demands rule; FORFEIT admits defeat.\nREQUIRES AN ACTIVE SCHEME (started via ${start}).\nIf the plan is weak, improve it with ${drive}.',
-                criteriaChecks: 'REQUIRED. Proof of conquest for CLAIM, or reason for self-destruct.',
-                constraintsChecks: 'REQUIRED. Constraint-by-constraint compliance proof for CLAIM, or confession of violations for FORFEIT.',
-                score_precise: 'REQUIRED (0-10). Architectural placement. 10 = exact layer, exact boundary, zero misplacement.',
-                score_minimal: 'REQUIRED (0-10). Economy of change. 10 = no avoidable lines, no speculative edits, no hidden bloat.',
-                score_isolated: 'REQUIRED (0-10). Surgical containment. 10 = zero unrelated files, zero opportunistic cleanup, zero collateral.',
-                score_idiomatic: 'REQUIRED (0-10). Native fluency. 10 = naming, structure, style indistinguishable from the codebase.',
-                score_cohesive: 'REQUIRED (0-10). Single responsibility. 10 = each unit does one thing, boundaries intact.',
-                oath: "Mastermind's Vow. Required for CLAIM. Verbatim: ${oath_text}",
+                criteriaChecks: 'Required for CLAIM. Proof of conquest. For FORFEIT, optional (can be left empty).',
+                constraintsChecks: 'Required for CLAIM. Constraint-by-constraint compliance proof. For FORFEIT, optional (can be left empty).',
+                score_precise: 'Required for CLAIM (0-10). Architectural placement. 10 = exact layer, exact boundary, zero misplacement. For FORFEIT, optional.',
+                score_minimal: 'Required for CLAIM (0-10). Economy of change. 10 = no avoidable lines, no speculative edits, no hidden bloat. For FORFEIT, optional.',
+                score_isolated: 'Required for CLAIM (0-10). Surgical containment. 10 = zero unrelated files, zero opportunistic cleanup, zero collateral. For FORFEIT, optional.',
+                score_idiomatic: 'Required for CLAIM (0-10). Native fluency. 10 = naming, structure, style indistinguishable from the codebase. For FORFEIT, optional.',
+                score_cohesive: 'Required for CLAIM (0-10). Single responsibility. 10 = each unit does one thing, boundaries intact. For FORFEIT, optional.',
+                oath: "Mastermind's Vow. Required for CLAIM. For FORFEIT, optional. Verbatim: ${oath_text}",
                 cwd: 'Optional lair path (repository root). Defaults to current command chamber.',
             },
         },

package/build/handlers/close.js

@@ -2,8 +2,15 @@ import { appendDebugLog } from "../utils/debug-log.js";
 import { presentWork } from "../workflow/present.js";
 import { buildCloseDoneResponse, buildCloseDropResponse, } from "../workflow/response-builders.js";
 import { resolveTermPreset } from "../config/term-presets.js";
+import { FlowError } from "../common/errors.js";
 import { closeToolSchema } from "../types/tooling.js";
 import { handleToolError } from "./shared.js";
+function requireClaimField(value, name) {
+    if (value === undefined) {
+        throw new FlowError("EMPTY_PARAM", `parameter '${name}' is required when petition=CLAIM`);
+    }
+    return value;
+}
 export function createCloseHandler() {
     return async (args, extra) => {
         let petition = "UNKNOWN";
@@ -17,23 +24,47 @@ export function createCloseHandler() {
             petition = input.petition;
             workingDir = input.cwd || process.cwd();
             if (input.petition === "CLAIM") {
-                criteriaCheckParts = input.criteriaChecks;
-                constraintsCheckParts = input.constraintsChecks;
+                criteriaCheckParts = input.criteriaChecks ?? [];
+                constraintsCheckParts = input.constraintsChecks ?? [];
                 oath = input.oath;
-                scoreLine = `Scores: precise=${input.score_precise} minimal=${input.score_minimal} isolated=${input.score_isolated} idiomatic=${input.score_idiomatic} cohesive=${input.score_cohesive}`;
+                scoreLine = `Scores: precise=${input.score_precise ?? "MISSING"} minimal=${input.score_minimal ?? "MISSING"} isolated=${input.score_isolated ?? "MISSING"} idiomatic=${input.score_idiomatic ?? "MISSING"} cohesive=${input.score_cohesive ?? "MISSING"}`;
             }
             appendDebugLog(`tool close start petition=${petition} cwd=${workingDir} criteriaChecks=${criteriaCheckParts.length} constraintsChecks=${constraintsCheckParts.length}`, {
                 cwd: workingDir,
                 section: "script",
             });
-            const outcome = await presentWork({
-                ...input,
-                cwd: workingDir,
-                signal: extra.signal,
-            });
+            let closeInput;
+            let claimInput;
             if (input.petition === "CLAIM") {
+                claimInput = {
+                    petition: "CLAIM",
+                    criteriaChecks: requireClaimField(input.criteriaChecks, "criteriaChecks"),
+                    constraintsChecks: requireClaimField(input.constraintsChecks, "constraintsChecks"),
+                    score_precise: requireClaimField(input.score_precise, "score_precise"),
+                    score_minimal: requireClaimField(input.score_minimal, "score_minimal"),
+                    score_isolated: requireClaimField(input.score_isolated, "score_isolated"),
+                    score_idiomatic: requireClaimField(input.score_idiomatic, "score_idiomatic"),
+                    score_cohesive: requireClaimField(input.score_cohesive, "score_cohesive"),
+                    oath: requireClaimField(input.oath, "oath"),
+                    cwd: workingDir,
+                    signal: extra.signal,
+                };
+                closeInput = claimInput;
+            }
+            else {
+                closeInput = {
+                    petition: "FORFEIT",
+                    cwd: workingDir,
+                    signal: extra.signal,
+                };
+            }
+            const outcome = await presentWork(closeInput);
+            if (input.petition === "CLAIM") {
+                if (!claimInput) {
+                    throw new FlowError("INTERNAL_STATE", "Unexpected CLAIM input shape");
+                }
                 if (!("result" in outcome) || outcome.result !== "merged") {
-                    throw new Error("Unexpected CLAIM outcome shape");
+                    throw new FlowError("INTERNAL_STATE", "Unexpected CLAIM outcome shape");
                 }
                 const finalOutcome = outcome;
                 appendDebugLog(`tool close CLAIM success branch=${finalOutcome.currentBranch} base=${finalOutcome.baseBranch}`, {
@@ -43,17 +74,17 @@ export function createCloseHandler() {
                 return buildCloseDoneResponse(finalOutcome, {
                     criteriaChecks: criteriaCheckParts,
                     constraintsChecks: constraintsCheckParts,
-                    score_precise: input.score_precise,
-                    score_minimal: input.score_minimal,
-                    score_isolated: input.score_isolated,
-                    score_idiomatic: input.score_idiomatic,
-                    score_cohesive: input.score_cohesive,
-                    oath: input.oath,
+                    score_precise: claimInput.score_precise,
+                    score_minimal: claimInput.score_minimal,
+                    score_isolated: claimInput.score_isolated,
+                    score_idiomatic: claimInput.score_idiomatic,
+                    score_cohesive: claimInput.score_cohesive,
+                    oath: claimInput.oath,
                     cwd: workingDir,
                 });
             }
             if (!("result" in outcome) || outcome.result !== "dropped") {
-                throw new Error("Unexpected FORFEIT outcome shape");
+                throw new FlowError("INTERNAL_STATE", "Unexpected FORFEIT outcome shape");
             }
             const finalOutcome = outcome;
             appendDebugLog(`tool close FORFEIT success branch=${finalOutcome.currentBranch} base=${finalOutcome.baseBranch}`, {

package/build/handlers/shared.js

@@ -17,7 +17,7 @@ export function classifyToolError(error) {
 export function handleToolError(input) {
     const message = asMessage(input.error);
     appendDebugLog(`${input.logLabel} error: ${message}`, { cwd: input.cwd, section: "script" });
-    const hint = pickHintFromError(input.error, message);
+    const hint = pickHintFromError(input.error);
     const { errorType, errorCode } = classifyToolError(input.error);
     return buildToolErrorResponse({
         tool: input.toolName,

package/build/index.js

@@ -41,7 +41,9 @@ function registerTools(server) {
     const askPreset = renderedPreset.tools.ask;
     const closePreset = renderedPreset.tools.close;
     const helpPreset = renderedPreset.tools.help;
-    const dynamicCloseSchema = closeToolSchema;
+    const dynamicCloseSchema = applyArgumentDescriptions(closeToolSchema, {
+        ...closePreset.args,
+    });
     const dynamicStartSchema = applyArgumentDescriptions(startToolSchema, {
         ...startPreset.args,
     });

package/build/types/tooling.js

@@ -22,22 +22,54 @@ export const askToolSchema = z.object({
     name: z.string().optional(),
     cwd: z.string().optional(),
 });
-export const closeToolSchema = z.discriminatedUnion("petition", [
-    z.object({
-        petition: z.literal("CLAIM"),
-        criteriaChecks: z.array(z.string().trim().min(1)).min(1),
-        constraintsChecks: z.array(z.string().trim().min(1)).min(1),
-        score_precise: z.number().min(0).max(10),
-        score_minimal: z.number().min(0).max(10),
-        score_isolated: z.number().min(0).max(10),
-        score_idiomatic: z.number().min(0).max(10),
-        score_cohesive: z.number().min(0).max(10),
-        oath: z.string().optional(),
-        cwd: z.string().optional(),
-    }),
-    z.object({
-        petition: z.literal("FORFEIT"),
-        cwd: z.string().optional(),
-    }),
-]);
+export const closeToolSchema = z.object({
+    petition: z.enum(["CLAIM", "FORFEIT"]).describe("REQUIRED. CLAIM to finalize, FORFEIT to abandon."),
+    criteriaChecks: z
+        .array(z.string().trim().min(1))
+        .min(1)
+        .optional()
+        .describe("Required when petition=CLAIM. For FORFEIT, this field is optional and can be omitted."),
+    constraintsChecks: z
+        .array(z.string().trim().min(1))
+        .min(1)
+        .optional()
+        .describe("Required when petition=CLAIM. For FORFEIT, this field is optional and can be omitted."),
+    score_precise: z
+        .number()
+        .min(0)
+        .max(10)
+        .optional()
+        .describe("Required when petition=CLAIM. For FORFEIT, this field is optional and can be omitted."),
+    score_minimal: z
+        .number()
+        .min(0)
+        .max(10)
+        .optional()
+        .describe("Required when petition=CLAIM. For FORFEIT, this field is optional and can be omitted."),
+    score_isolated: z
+        .number()
+        .min(0)
+        .max(10)
+        .optional()
+        .describe("Required when petition=CLAIM. For FORFEIT, this field is optional and can be omitted."),
+    score_idiomatic: z
+        .number()
+        .min(0)
+        .max(10)
+        .optional()
+        .describe("Required when petition=CLAIM. For FORFEIT, this field is optional and can be omitted."),
+    score_cohesive: z
+        .number()
+        .min(0)
+        .max(10)
+        .optional()
+        .describe("Required when petition=CLAIM. For FORFEIT, this field is optional and can be omitted."),
+    oath: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe("Required when petition=CLAIM. For FORFEIT, this field is optional and can be omitted."),
+    cwd: z.string().optional(),
+});
 export const helpToolSchema = z.object({});

package/build/utils/git-ops.js

@@ -1,4 +1,5 @@
 import { simpleGit } from "simple-git";
+import { FlowError } from "../common/errors.js";
 import { appendDebugBlock } from "./debug-log.js";
 const DEFAULT_GIT_TIMEOUT_MS = 15 * 1000;
 function readPositiveIntEnv(name, fallback) {
@@ -80,7 +81,7 @@ export async function getCurrentBranch(cwd) {
         throw wrapGitError("status", err, cwd);
     }
     if (!status.current) {
-        throw new Error("Detached HEAD or no branch found");
+        throw new FlowError("DETACHED_HEAD", "Detached HEAD or no branch found");
     }
     return status.current;
 }
@@ -234,6 +235,34 @@ export async function getDirtyPaths(cwd) {
     const files = await getDirtyFiles(cwd);
     return Array.from(new Set(files.map(f => f.path)));
 }
+export async function isPathTracked(cwd, filePath) {
+    const git = createGit(cwd);
+    let output;
+    try {
+        output = await git.raw(["ls-files", "--", filePath]);
+    }
+    catch (err) {
+        throw wrapGitError(`ls-files -- ${filePath}`, err, cwd);
+    }
+    return output
+        .split(/\r?\n/)
+        .some((line) => line.trim() === filePath);
+}
+export async function discardAllWorkingTreeChanges(cwd) {
+    const git = createGit(cwd);
+    try {
+        await git.raw(["reset", "--hard", "HEAD"]);
+    }
+    catch (err) {
+        throw wrapGitError("reset --hard HEAD", err, cwd);
+    }
+    try {
+        await git.raw(["clean", "-fd"]);
+    }
+    catch (err) {
+        throw wrapGitError("clean -fd", err, cwd);
+    }
+}
 export async function assertValidBranchName(cwd, branchName) {
     const git = createGit(cwd);
     try {

package/build/utils/text-utils.js

@@ -8,17 +8,27 @@ function isPlainObject(value) {
 export function flattenMarkdownList(text) {
     const ast = parseToAST(text, { allowSections: false });
     const items = [];
-    let currentTitle;
+    const headingStack = [];
     const pushItem = (content) => {
         const trimmed = content.trim();
         if (!trimmed)
             return;
-        const prefix = currentTitle ? `**${currentTitle.replace(/^\d+\.\s*/, "")}**: ` : "";
+        const headingPath = headingStack.map((entry) => entry.title);
+        const prefix = headingPath.length > 0 ? `**${headingPath.join(" > ")}**: ` : "";
         items.push(`${prefix}${trimmed}`);
     };
+    const updateHeadingPath = (level, rawText) => {
+        const title = rawText.trim().replace(/^\d+\.\s*/, "");
+        if (!title)
+            return;
+        while (headingStack.length > 0 && headingStack[headingStack.length - 1].level >= level) {
+            headingStack.pop();
+        }
+        headingStack.push({ level, title });
+    };
     for (const node of ast.children) {
         if (node.type === "heading") {
-            currentTitle = node.text.trim();
+            updateHeadingPath(node.level, node.text);
             continue;
         }
         if (node.type === "list") {

package/build/workflow/contract.js

@@ -6,6 +6,7 @@ import { FlowError } from "../common/errors.js";
 import * as git from "../utils/git.js";
 import { resolveOath } from "./oath.js";
 export { resolveOath };
+const DIRTY_WORKTREE_LIST_LIMIT = 10;
 export async function ensureKeiyakuFiles(cwd) {
     const keiyakuPath = path.join(cwd, KEIYAKU_FILE);
     const tracePath = path.join(cwd, TRACE_FILE);
@@ -36,13 +37,21 @@ export async function assertCleanWorkingTree(cwd, ignorePatterns) {
         .getDirtyFiles(cwd)
         .then((files) => files.filter((file) => !ignoredPaths.has(normalizePathForDirtyMatch(cwd, file.path))));
     if (dirtyFiles.length > 0) {
-        const list = dirtyFiles
+        const shown = dirtyFiles.slice(0, DIRTY_WORKTREE_LIST_LIMIT);
+        const list = shown
             .map((f) => {
             const status = `${f.index}${f.working_dir}`;
             return `  ${status} ${f.path}`;
         })
             .join("\n");
-        throw new FlowError("DIRTY_WORKTREE", `Uncommitted changes detected in working tree:\n${list}\n\nPlease commit or stash them before proceeding to ensure a stable state.`);
+        const overflowCount = dirtyFiles.length - shown.length;
+        const overflowLine = overflowCount > 0 ? `\n  ... (+${overflowCount} more)` : "";
+        const ignoredList = ignoredPaths.size > 0
+            ? `\n\nIgnored uncommitted paths (not blocking):\n${Array.from(ignoredPaths)
+                .map((pathValue) => `  - ${pathValue}`)
+                .join("\n")}`
+            : "";
+        throw new FlowError("DIRTY_WORKTREE", `Uncommitted changes detected in working tree:\n${list}${overflowLine}${ignoredList}\n\nPlease commit or stash blocking changes before proceeding.`);
     }
 }
 export async function buildNoActiveKeiyakuGuidance(cwd, toolName) {

package/build/workflow/drive.js

@@ -55,6 +55,7 @@ export async function driveServant(input) {
         await appendReview(cwd, plan.targetRound, plan.reviewReason);
         await git.addFiles(cwd, TRACE_FILE);
         await git.commit(cwd, `keiyaku(${title}): iterate round ${plan.targetRound}`);
+        const commit = await git.getLatestCommitHash(cwd);
         const { roundSummary } = await runAndRecordRound(cwd, title, plan.targetRound, plan.prompt, {
             signal,
             name,
@@ -63,6 +64,7 @@ export async function driveServant(input) {
                 await appendRoundSystemNote(cwd, plan.targetRound, "Subagent execution cancelled by user/client.");
                 await git.addFiles(cwd, TRACE_FILE);
                 await git.commit(cwd, `keiyaku(${title}): round ${plan.targetRound} cancelled`);
+                await git.getLatestCommitHash(cwd);
             },
         });
         const summary = renderRoundSummary(roundSummary, TOOL_DEFAULT_POLICY);
@@ -77,6 +79,7 @@ export async function driveServant(input) {
             criteria,
             currentBranch: keiyakuBranch,
             baseBranch,
+            commit,
         };
     }
     catch (err) {

package/build/workflow/present.js

@@ -1,6 +1,6 @@
 import * as fs from "fs/promises";
 import * as path from "path";
-import { KEIYAKU_FILE, TRACE_FILE } from "../common/constants.js";
+import { KEIYAKU_DRAFT_FILE, KEIYAKU_DRAFT_NEW_FILE, KEIYAKU_FILE, TRACE_FILE } from "../common/constants.js";
 import { resolveTermPreset } from "../config/term-presets.js";
 import { appendDebugLog } from "../utils/debug-log.js";
 import { FlowError, wrapFlowError } from "../common/errors.js";
@@ -95,6 +95,27 @@ function requireChecks(name, values) {
     }
     return values;
 }
+async function removeClaimProtocolFiles(cwd) {
+    await fs.unlink(path.join(cwd, KEIYAKU_FILE));
+    await fs.unlink(path.join(cwd, TRACE_FILE));
+    const draftCandidates = [KEIYAKU_DRAFT_FILE, KEIYAKU_DRAFT_NEW_FILE];
+    for (const draftPath of draftCandidates) {
+        const tracked = await git.isPathTracked(cwd, draftPath);
+        if (tracked)
+            continue;
+        try {
+            await fs.unlink(path.join(cwd, draftPath));
+        }
+        catch (error) {
+            if (error?.code !== "ENOENT") {
+                throw error;
+            }
+        }
+    }
+}
+function formatCloseDiffSummary(stats, baseBranch) {
+    return `Range ${baseBranch}...HEAD | Files ${stats.filesChanged} | +${stats.insertions} / -${stats.deletions}`;
+}
 export async function presentWork(input) {
     const { cwd } = input;
     const isRepo = await git.isGitRepo(cwd);
@@ -120,8 +141,12 @@ export async function presentWork(input) {
         catch {
             round = 0;
         }
-        await assertCleanWorkingTree(cwd);
+        const dirtyFiles = await git.getDirtyFiles(cwd);
+        const droppedChanges = dirtyFiles.map((file) => `${file.index}${file.working_dir} ${file.path}`);
         try {
+            if (droppedChanges.length > 0) {
+                await git.discardAllWorkingTreeChanges(cwd);
+            }
             await git.checkoutBranch(cwd, baseBranch);
             await git.deleteBranch(cwd, keiyakuBranch, true);
             await git.clearKeiyakuBase(cwd, keiyakuBranch);
@@ -136,7 +161,10 @@ export async function presentWork(input) {
             currentBranch: baseBranch,
             baseBranch,
             deletedBranch: keiyakuBranch,
-            diff: "Forfeited without merge.",
+            diff: droppedChanges.length > 0
+                ? `Forfeited without merge. Dropped ${droppedChanges.length} local change(s).`
+                : "Forfeited without merge.",
+            droppedChanges,
         };
     }
     await ensureKeiyakuFiles(cwd);
@@ -169,7 +197,7 @@ export async function presentWork(input) {
         if (!oathMatches(input.oath, expectedOath)) {
             throw new FlowError("OATH_MISMATCH", `Oath mismatch. Correct oath: ${expectedOath}`);
         }
-        await assertCleanWorkingTree(cwd);
+        await assertCleanWorkingTree(cwd, [KEIYAKU_DRAFT_FILE, KEIYAKU_DRAFT_NEW_FILE]);
         try {
             const invokeDiffLog = `[CLAIM] Collecting diff preview against base '${baseBranch}'`;
             console.error(invokeDiffLog);
@@ -179,14 +207,14 @@ export async function presentWork(input) {
             appendDebugLog(invokeReadLog, { cwd, section: "script" });
             const keiyakuContent = await fs.readFile(path.join(cwd, KEIYAKU_FILE), "utf-8");
             const message = buildMergeMessage(title, keiyakuContent, traceContent);
+            const diffStats = await git.getDiffStats(cwd, baseBranch);
+            const diff = formatCloseDiffSummary(diffStats, baseBranch);
             const invokeCleanupLog = "[CLAIM] Removing protocol files and creating cleanup commit";
             console.error(invokeCleanupLog);
             appendDebugLog(invokeCleanupLog, { cwd, section: "script" });
-            await fs.unlink(path.join(cwd, KEIYAKU_FILE));
-            await fs.unlink(path.join(cwd, TRACE_FILE));
+            await removeClaimProtocolFiles(cwd);
             await git.addFiles(cwd, "-A");
             await git.commit(cwd, `keiyaku(${title}): cleanup`);
-            const diff = await git.getDiffPreviewText(cwd, baseBranch);
             const invokeCheckoutLog = `[CLAIM] Checking out base branch '${baseBranch}'`;
             console.error(invokeCheckoutLog);
             appendDebugLog(invokeCheckoutLog, { cwd, section: "script" });
@@ -195,7 +223,7 @@ export async function presentWork(input) {
             console.error(invokeMergeLog);
             appendDebugLog(invokeMergeLog, { cwd, section: "script" });
             await git.merge(cwd, keiyakuBranch, message);
-            const mergedCommit = await git.getLatestCommitHash(cwd);
+            const commit = await git.getLatestCommitHash(cwd);
             const invokeFinalizeLog = `[CLAIM] Deleting merged branch '${keiyakuBranch}' and clearing metadata`;
             console.error(invokeFinalizeLog);
             appendDebugLog(invokeFinalizeLog, { cwd, section: "script" });
@@ -208,7 +236,7 @@ export async function presentWork(input) {
                 round,
                 currentBranch: baseBranch,
                 baseBranch,
-                mergedCommit,
+                commit,
                 mergedInto: baseBranch,
                 deletedBranch: keiyakuBranch,
                 diff,
@@ -222,5 +250,5 @@ export async function presentWork(input) {
             throw wrapFlowError(`execute CLAIM (merge ${keiyakuBranch} into ${baseBranch})`, err);
         }
     }
-    throw new Error(`unsupported close petition: ${petition}`);
+    throw new FlowError("INVALID_CLOSE_PETITION", `unsupported close petition: ${petition}`);
 }

package/build/workflow/response-builders.js

@@ -135,8 +135,12 @@ export function buildKeiyakuSuccessResponse(result, input) {
         ...formatMaybe("Path", input.cwd, 300),
         ...formatMaybe("Current Branch", result.currentBranch, 200),
         ...formatMaybe("Base Branch", result.baseBranch, 200),
+        ...formatMaybe("Commit", result.commit, 100),
     ];
-    const text = assembleResponse(`◆ Started (Round ${result.round})`, `Created branch '${result.currentBranch}' (base: '${result.baseBranch}').`, [summarySection, constraintsSection, diffSection].filter((section) => section !== null), infoLines);
+    const summaryLine = result.commit
+        ? `Created branch '${result.currentBranch}' (base: '${result.baseBranch}') [${result.commit}].`
+        : `Created branch '${result.currentBranch}' (base: '${result.baseBranch}').`;
+    const text = assembleResponse(`◆ Started (Round ${result.round})`, summaryLine, [summarySection, constraintsSection, diffSection].filter((section) => section !== null), infoLines);
     return {
         content: [{ type: "text", text }],
         structuredContent: buildSuccessStructuredContent(getStartToolName(), resultData),
@@ -154,8 +158,12 @@ export function buildDriveResponse(result, input) {
         ...formatMaybe("Path", input.cwd, 300),
         ...formatMaybe("Current Branch", result.currentBranch, 200),
         ...formatMaybe("Base Branch", result.baseBranch, 200),
+        ...formatMaybe("Commit", result.commit, 100),
     ];
-    const text = assembleResponse(`◆ Driven (Round ${result.round})`, `Updated branch '${result.currentBranch}'.`, [summarySection, goalSection, constraintsSection, criteriaSection, diffSection].filter((section) => section !== null), infoLines);
+    const summaryLine = result.commit
+        ? `Updated branch '${result.currentBranch}' [${result.commit}].`
+        : `Updated branch '${result.currentBranch}'.`;
+    const text = assembleResponse(`◆ Driven (Round ${result.round})`, summaryLine, [summarySection, goalSection, constraintsSection, criteriaSection, diffSection].filter((section) => section !== null), infoLines);
     return {
         content: [{ type: "text", text }],
         structuredContent: buildSuccessStructuredContent(getDriveToolName(), resultData),
@@ -181,7 +189,7 @@ export function buildCloseDoneResponse(result, input) {
     const infoLines = [
         ...formatMaybe("Path", input.cwd, 300),
         ...formatMaybe("Result", result.result, 100),
-        ...formatMaybe("Merged Commit", result.mergedCommit, 100),
+        ...formatMaybe("Commit", result.commit, 100),
         ...formatMaybe("Merged Into", result.mergedInto, 200),
         ...formatMaybe("Deleted Branch", result.deletedBranch, 200),
         ...formatMaybe("Current Branch", result.currentBranch, 200),
@@ -191,7 +199,9 @@ export function buildCloseDoneResponse(result, input) {
         `Scores: precise=${input.score_precise}/10 minimal=${input.score_minimal}/10 isolated=${input.score_isolated}/10 idiomatic=${input.score_idiomatic}/10 cohesive=${input.score_cohesive}/10`,
         ...formatMaybe("Oath", input.oath, 220),
     ];
-    const text = assembleResponse("✓ Keiyaku Fulfilled (CLAIM)", `Merged '${result.deletedBranch}' into '${result.mergedInto}' (commit: ${result.mergedCommit}). Deleted feature branch.`, [typeof diffSection === "string" ? null : diffSection].filter((section) => section !== null), infoLines);
+    const text = assembleResponse("✓ Keiyaku Fulfilled (CLAIM)", result.commit
+        ? `Merged '${result.deletedBranch}' into '${result.mergedInto}' [${result.commit}]. Deleted feature branch.`
+        : `Merged '${result.deletedBranch}' into '${result.mergedInto}'. Deleted feature branch.`, [typeof diffSection === "string" ? null : diffSection].filter((section) => section !== null), infoLines);
     return {
         content: [{ type: "text", text }],
         structuredContent: buildSuccessStructuredContent(closeToolName, resultData),
@@ -200,13 +210,17 @@ export function buildCloseDoneResponse(result, input) {
 export function buildCloseDropResponse(result, input) {
     const { status: _status, ...resultData } = result;
     const closeToolName = getCloseToolName();
+    const droppedChanges = result.droppedChanges ?? [];
+    const warningSection = buildSection("Warning", formatList("Dropped Local Changes", droppedChanges, { maxItems: 20, maxItemChars: 220 }));
     const infoLines = [
         ...formatMaybe("Path", input.cwd, 300),
         ...formatMaybe("Deleted Branch", result.deletedBranch, 200),
         ...formatMaybe("Current Branch", result.currentBranch, 200),
         ...formatMaybe("Base Branch", result.baseBranch, 200),
     ];
-    const text = assembleResponse("✗ Keiyaku Forfeited (FORFEIT)", `Deleted '${result.deletedBranch}'. Switched back to '${result.baseBranch}'.`, [], infoLines);
+    const text = assembleResponse("✗ Keiyaku Forfeited (FORFEIT)", droppedChanges.length > 0
+        ? `Deleted '${result.deletedBranch}'. Switched back to '${result.baseBranch}'. Dropped ${droppedChanges.length} local change(s).`
+        : `Deleted '${result.deletedBranch}'. Switched back to '${result.baseBranch}'.`, [warningSection].filter((section) => section !== null), infoLines);
     return {
         content: [{ type: "text", text }],
         structuredContent: buildSuccessStructuredContent(closeToolName, resultData),

package/build/workflow/start.js

@@ -15,6 +15,7 @@ import { runAndRecordRound } from "./round.js";
 const BASE_CONSTRAINTS_FILE = path.join(".keiyaku", "base-constraints.md");
 const ACTIVE_KEIYAKU_PREVIEW_MAX_CHARS = 8000;
 const KNOWN_SECTIONS = new Set(["goal", "directive", "context", "constraints", "criteria", "acceptance criteria"]);
+const INTERNAL_START_DIRTY_ALLOWLIST = [];
 function normalizeSectionTitle(title) {
     return title.trim().toLowerCase().replace(/\s+/g, " ");
 }
@@ -268,6 +269,7 @@ function normalizeTitleForBranch(title) {
 }
 async function resolveStartInput(cwd, input) {
     const fromFile = normalizeOptionalText(input.from_file);
+    const dirtyAllowlist = [...INTERNAL_START_DIRTY_ALLOWLIST];
     const provided = {
         title: normalizeOptionalText(input.title),
         goal: normalizeOptionalText(input.goal),
@@ -297,6 +299,7 @@ async function resolveStartInput(cwd, input) {
             criteria: normalizeMarkdownListItems("criteria", provided.criteria),
             constraints: normalizeMarkdownListItems("constraints", provided.constraints ?? []),
             fromFile: undefined,
+            dirtyAllowlist,
         };
     }
     const draftPath = path.isAbsolute(fromFile) ? fromFile : path.join(cwd, fromFile);
@@ -337,6 +340,7 @@ async function resolveStartInput(cwd, input) {
         criteria: normalizeMarkdownListItems("criteria", criteria),
         constraints: normalizeMarkdownListItems("constraints", constraints),
         fromFile,
+        dirtyAllowlist,
     };
 }
 async function readBaseConstraints(cwd) {
@@ -431,7 +435,8 @@ export async function startKeiyaku(input) {
             appendDebugLog(branchWarning, { cwd, section: "script" });
         }
         await assertStartPreFlight(cwd, resolved.fromFile);
-        await assertCleanWorkingTree(cwd, resolved.fromFile ? [resolved.fromFile] : undefined);
+        const dirtyAllowlist = Array.from(new Set([...(resolved.fromFile ? [resolved.fromFile] : []), ...resolved.dirtyAllowlist]));
+        await assertCleanWorkingTree(cwd, dirtyAllowlist.length > 0 ? dirtyAllowlist : undefined);
         baseBranch = await git.getCurrentBranch(cwd);
         const branchToken = normalizeTitleForBranch(resolved.title);
         keiyakuBranch = `keiyaku/${branchToken}`;
@@ -454,6 +459,7 @@ export async function startKeiyaku(input) {
         await fs.writeFile(path.join(cwd, TRACE_FILE), "# Keiyaku Trace\n");
         await git.addFiles(cwd, [KEIYAKU_FILE, TRACE_FILE]);
         await git.commit(cwd, `keiyaku(${branchToken}): open`);
+        const commit = await git.getLatestCommitHash(cwd);
         const prompt = buildStartPrompt(resolved.title, resolved.goal, resolved.directive);
         const { roundSummary } = await runAndRecordRound(cwd, branchToken, 1, prompt, {
             signal,
@@ -480,6 +486,7 @@ export async function startKeiyaku(input) {
             constraints: constraintsSection,
             currentBranch: keiyakuBranch,
             baseBranch,
+            commit,
         };
     }
     catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/keiyaku",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "MCP server for running iterative keiyaku workflows with Codex subagents.",
   "license": "MIT",
   "type": "module",