@astrosheep/keiyaku 0.1.21 → 0.1.23

package/build/workflow/keiyaku-draft.js

@@ -1,10 +1,11 @@
 import { FlowError } from "../common/errors.js";
 import { extractListItems, parseToAST, renderSectionContent, } from "../utils/keiyaku-document.js";
+import { computeHeadingDelta } from "./markdown-normalization.js";
 const KNOWN_DRAFT_SECTIONS = new Set([
     "goal",
     "directive",
     "context",
-    "constraints",
+    "rules",
     "criteria",
     "acceptance criteria",
 ]);
@@ -131,10 +132,10 @@ function normalizeDraftHeadings(content) {
         }
         shallowestNonStructural = shallowestNonStructural === null ? level : Math.min(shallowestNonStructural, level);
     }
-    if (shallowestNonStructural === null || shallowestNonStructural >= MIN_HEADING_LEVEL) {
+    const delta = computeHeadingDelta(shallowestNonStructural, MIN_HEADING_LEVEL);
+    if (delta === 0) {
         return lines.join("\n");
     }
-    const delta = MIN_HEADING_LEVEL - shallowestNonStructural;
     const out = [];
     sawTitleH1 = false;
     fence = null;
@@ -238,7 +239,7 @@ export function parseAndValidateKeiyakuDraft(content) {
     const goal = sections.get("goal")?.trim();
     const directive = sections.get("directive")?.trim();
     const context = sections.get("context")?.trim();
-    const constraints = sections.has("constraints") ? collectSectionItems(ast, "constraints") : undefined;
+    const rules = sections.has("rules") ? collectSectionItems(ast, "rules") : undefined;
     const criteria = sections.has("acceptance criteria")
         ? collectSectionItems(ast, "acceptance criteria")
         : sections.has("criteria")
@@ -249,7 +250,7 @@ export function parseAndValidateKeiyakuDraft(content) {
         goal: goal || undefined,
         directive: directive || undefined,
         context: context || undefined,
-        constraints: constraints && constraints.length > 0 ? constraints : undefined,
+        rules: rules && rules.length > 0 ? rules : undefined,
         criteria: criteria && criteria.length > 0 ? criteria : undefined,
     };
 }

package/build/workflow/markdown-normalization.js

@@ -0,0 +1,69 @@
+import { parseToAST, renderNodeContent, } from "../utils/keiyaku-document.js";
+export function computeHeadingDelta(shallowest, minLevel) {
+    if (shallowest === null || shallowest >= minLevel) {
+        return 0;
+    }
+    return minLevel - shallowest;
+}
+export function demoteMarkdownHeadings(text, minLevel = 3) {
+    const ast = parseToAST(text, { allowSections: false });
+    // Preserve relative heading hierarchy by shifting all headings together.
+    // This avoids collapsing something like `# A` and `### B` into the same level.
+    let shallowest = null;
+    {
+        const stack = [ast];
+        while (stack.length > 0) {
+            const node = stack.pop();
+            if (!node)
+                continue;
+            if (node.type === "heading") {
+                shallowest = shallowest === null ? node.level : Math.min(shallowest, node.level);
+            }
+            if (node.type === "code_block" || node.type === "text")
+                continue;
+            if (node.type === "document" || node.type === "section" || node.type === "list_item") {
+                stack.push(...node.children);
+            }
+            else if (node.type === "list") {
+                stack.push(...node.items);
+            }
+        }
+    }
+    const delta = computeHeadingDelta(shallowest, minLevel);
+    if (delta === 0) {
+        // Return a normalized render (trimEnd) to avoid leaking extra trailing newlines.
+        return renderNodeContent(ast).trimEnd();
+    }
+    const shift = (node) => {
+        switch (node.type) {
+            case "heading": {
+                const nextLevel = Math.min(6, node.level + delta);
+                return nextLevel === node.level ? node : { ...node, level: nextLevel };
+            }
+            case "code_block":
+            case "text":
+                return node;
+            case "document":
+            case "section":
+                return { ...node, children: node.children.map((child) => shift(child)) };
+            case "list":
+                return { ...node, items: node.items.map((item) => shift(item)) };
+            case "list_item":
+                return { ...node, children: node.children.map((child) => shift(child)) };
+        }
+    };
+    return renderNodeContent(shift(ast)).trimEnd();
+}
+export function renderMarkdownSections(items) {
+    return items
+        .map((item) => {
+        // Keiyaku uses H2 as contract section delimiters. Keep payload headings at H3+.
+        const normalized = demoteMarkdownHeadings(item, 3);
+        const trimmed = normalized.trimStart();
+        if (/^[-*+]\s+/.test(trimmed) || /^\d+\.\s+/.test(trimmed)) {
+            return normalized;
+        }
+        return `- ${normalized}`;
+    })
+        .join("\n\n");
+}

package/build/workflow/present.js

@@ -29,6 +29,14 @@ const SCORE_FIELD_TO_COMMANDMENT = {
     score_idiomatic: "Commandment of Idiom",
     score_cohesive: "Commandment of Cohesion",
 };
+const SCORE_FIELD_TO_DEFINITION = {
+    score_precise: "Architectural placement. 10 = exact layer, exact boundary, zero misplacement.",
+    score_minimal: "Economy of change. 10 = no avoidable lines, no speculative edits, no hidden bloat.",
+    score_isolated: "Surgical containment. 10 = zero unrelated files, zero opportunistic cleanup, zero collateral.",
+    score_idiomatic: "Native fluency. 10 = naming, structure, style indistinguishable from the codebase.",
+    score_cohesive: "Single responsibility. 10 = each unit does one thing, boundaries intact.",
+};
+const VERDICT_DENIED_CODE = "VERDICT_DENIED";
 const VERDICT_SETTINGS_FILE = path.join(".keiyaku", "settings.json");
 function clampThreshold(value, fallback) {
     if (typeof value !== "number" || !Number.isFinite(value))
@@ -67,7 +75,7 @@ async function resolveVerdictConfig(cwd) {
         parsed = JSON.parse(rawSettings);
     }
     catch (error) {
-        throw new FlowError("CLOSE_QUALITY_GATE_FAILED", "Configuration Error: Invalid settings in .keiyaku/settings.json (must be valid JSON).", error);
+        throw new FlowError(VERDICT_DENIED_CODE, "Configuration Error: Invalid settings in .keiyaku/settings.json (must be valid JSON).", error);
     }
     if (!parsed || typeof parsed !== "object") {
         return merged;
@@ -137,10 +145,12 @@ export async function presentWork(input) {
             }
         }
         const dirtyFiles = await git.getDirtyFiles(cwd);
-        const droppedChanges = dirtyFiles.map((file) => `${file.index}${file.working_dir} ${file.path}`);
+        const droppedChanges = dirtyFiles
+            .filter((file) => file.path !== KEIYAKU_DRAFT_FILE)
+            .map((file) => `${file.index}${file.working_dir} ${file.path}`);
         try {
-            if (droppedChanges.length > 0) {
-                await git.discardAllWorkingTreeChanges(cwd);
+            if (dirtyFiles.length > 0) {
+                await git.discardWorkingTreeChangesExcluding(cwd, [KEIYAKU_DRAFT_FILE]);
             }
             await git.checkoutBranch(cwd, baseBranch);
             await git.deleteBranch(cwd, keiyakuBranch, true);
@@ -182,7 +192,7 @@ export async function presentWork(input) {
     const traceContent = await readTraceContent(cwd);
     if (petition === "CLAIM") {
         requireChecks("criteriaChecks", input.criteriaChecks);
-        requireChecks("constraintsChecks", input.constraintsChecks);
+        requireChecks("rulesChecks", input.rulesChecks);
         const verdict = await resolveVerdictConfig(cwd);
         const failedCommandments = CLOSE_SCORE_FIELDS.flatMap((field) => {
             const score = input[field];
@@ -190,7 +200,8 @@ export async function presentWork(input) {
             const threshold = verdict.thresholds[dimension];
             if (score >= threshold)
                 return [];
-            return [`${SCORE_FIELD_TO_COMMANDMENT[field]} broke (${field}=${score}, requires >= ${threshold})`];
+            const definition = SCORE_FIELD_TO_DEFINITION[field];
+            return [`${SCORE_FIELD_TO_COMMANDMENT[field]} broke (${field}=${score}). Definition: ${definition}`];
         });
         const totalScore = CLOSE_SCORE_FIELDS.reduce((sum, field) => sum + input[field], 0);
         const totalDeficit = verdict.minTotalScore - totalScore;
@@ -202,7 +213,7 @@ export async function presentWork(input) {
             failures.push(`Total devotion deficit: ${totalScore}/${verdict.minTotalScore} (short by ${totalDeficit})`);
         }
         if (failures.length > 0) {
-            throw new FlowError("CLOSE_QUALITY_GATE_FAILED", `Verdict Denied. ${failures.join(". ")}`);
+            throw new FlowError(VERDICT_DENIED_CODE, `Verdict Denied. ${failures.join(". ")}`);
         }
         const expectedOath = resolveOath();
         if (!oathMatches(input.oath, expectedOath)) {

package/build/workflow/prompts.js

@@ -10,14 +10,14 @@ Round: 1 (initial implementation).
 
 1. Read KEIYAKU.md. Use it as source of truth.
 2. If Directive exists, prioritize it. Otherwise, focus on the Goal and Criteria.
-3. Treat all constraints/criteria as required mission boundaries.
+3. Treat all rules/criteria as required mission boundaries.
 4. Read KEIYAKU_TRACE.md if present.
 5. Execute:
    - Stay within the scope defined by the Directive (or Goal if no Directive exists).
-   - Do not violate constraints.
+   - Do not violate rules.
    - Aim to progress toward criteria.
    - Match existing structure.
-6. Final Audit: Ensure the ${auditTarget} is fully addressed and no constraints are violated.
+6. Final Audit: Ensure the ${auditTarget} is fully addressed and no rules are violated.
 7. Reporting: End with exactly these 6 sections. Use the template below exactly; replace bracketed placeholders with your content. Mark Criteria status (MET/PARTIAL/TODO) honestly based on this round's progress.
 
 ## Outcome
@@ -41,8 +41,8 @@ Self-critique (The Delta). Focus only on what is missing or imperfect relative t
 ## Criteria Check
 - [List each criterion and its status: MET/PARTIAL/TODO]
 
-## Constraints Check
-- [List each constraint and confirm compliance: COMPLIANT/VIOLATED]
+## Rules Check
+- [List each rule and confirm compliance: COMPLIANT/VIOLATED]
 
 No git commands. Do not edit KEIYAKU_TRACE.md.`;
 }
@@ -53,13 +53,13 @@ export function buildIteratePrompt(title, round, goal, directive, context) {
     return `You are working on a keiyaku (${title}).${goalBlock}${directiveBlock}${contextBlock}
 Round: ${round} (iteration after review).
 
-1. Read KEIYAKU.md. Keep constraints/criteria unchanged.
+1. Read KEIYAKU.md. Keep rules/criteria unchanged.
 2. If Directive/Context exists, prioritize them.
 3. Read KEIYAKU_TRACE.md. Locate feedback from the previous completed round (typically the latest relevant "## Review" section), or generic feedback when a numbered review is absent.
 4. Execute according to the Directive while addressing previous feedback and incorporating any New Context.
-5. No drift from constraints/criteria.
+5. No drift from rules/criteria.
 6. Keep diff small.
-7. Final Audit: Ensure the Directive is fully addressed and no constraints are violated.
+7. Final Audit: Ensure the Directive is fully addressed and no rules are violated.
 8. Reporting: End with exactly these 6 sections. Use the template below exactly; replace bracketed placeholders with your content. Mark Criteria status (MET/PARTIAL/TODO) honestly based on this round's progress.
 
 ## Outcome
@@ -83,14 +83,14 @@ Self-critique (The Delta). Focus only on what is missing or imperfect relative t
 ## Criteria Check
 - [List each criterion and its status: MET/PARTIAL/TODO]
 
-## Constraints Check
-- [List each constraint and confirm compliance: COMPLIANT/VIOLATED]
+## Rules Check
+- [List each rule and confirm compliance: COMPLIANT/VIOLATED]
 
 No git commands. Do not edit KEIYAKU_TRACE.md.`;
 }
-export function buildAskPrompt(request, context, referenceConstraints) {
-    const referenceBlock = referenceConstraints
-        ? `\nReference Constraints (project-level; use only if relevant to this ask):\n${referenceConstraints}\n`
+export function buildAskPrompt(request, context, referenceRules) {
+    const referenceBlock = referenceRules
+        ? `\nReference Rules (project-level; use only if relevant to this ask):\n${referenceRules}\n`
         : "";
     return `Ask mode. Stateless. No git commands.
 

package/build/workflow/response-builders.js

@@ -53,7 +53,7 @@ function colorizeErrorStatus(status) {
 }
 const SECTION_ICONS = {
     goal: "▸",
-    constraints: "!",
+    rules: "!",
     criteria: "✓",
     context: "◦",
     summary: "·",
@@ -128,11 +128,16 @@ function getAskToolName() {
 export function buildKeiyakuSuccessResponse(result, input) {
     const { status: _status, ...resultData } = result;
     const summarySection = buildSection("Summary", result.summary);
-    const constraintsSection = buildSection("Constraints", truncateForDisplay(result.constraints, 1200));
+    const rulesSection = buildSection("Rules", truncateForDisplay(result.rules, 1200));
     const diffSection = buildSection("Diff", result.diff);
     const infoLines = [
         ...formatMaybe("Identity", input.name, 120),
         ...formatMaybe("Path", input.cwd, 300),
+        ...formatMaybe("Consumed from_file and deleted", result.consumedFromFile, 300),
+        ...formatList("Existing local keiyaku branches (non-blocking)", result.existingBranches ?? [], {
+            maxItems: 10,
+            maxItemChars: 220,
+        }),
         ...formatMaybe("Current Branch", result.currentBranch, 200),
         ...formatMaybe("Base Branch", result.baseBranch, 200),
         ...formatMaybe("Commit", result.commit, 100),
@@ -140,7 +145,7 @@ export function buildKeiyakuSuccessResponse(result, input) {
     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);
+    const text = assembleResponse(`◆ Started (Round ${result.round})`, summaryLine, [summarySection, rulesSection, diffSection].filter((section) => section !== null), infoLines);
     return {
         content: [{ type: "text", text }],
         structuredContent: buildSuccessStructuredContent(getStartToolName(), resultData),
@@ -150,7 +155,7 @@ export function buildDriveResponse(result, input) {
     const { status: _status, ...resultData } = result;
     const summarySection = buildSection("Summary", result.summary);
     const goalSection = buildSection("Goal", truncateForDisplay(result.goal, 800));
-    const constraintsSection = buildSection("Constraints", truncateForDisplay(result.constraints ?? "", 1200));
+    const rulesSection = buildSection("Rules", truncateForDisplay(result.rules ?? "", 1200));
     const criteriaSection = buildSection("Criteria", truncateForDisplay(result.criteria ?? "", 1200));
     const diffSection = buildSection("Diff", result.diff);
     const infoLines = [
@@ -163,7 +168,7 @@ export function buildDriveResponse(result, input) {
     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);
+    const text = assembleResponse(`◆ Driven (Round ${result.round})`, summaryLine, [summarySection, goalSection, rulesSection, criteriaSection, diffSection].filter((section) => section !== null), infoLines);
     return {
         content: [{ type: "text", text }],
         structuredContent: buildSuccessStructuredContent(getDriveToolName(), resultData),
@@ -195,7 +200,7 @@ export function buildCloseDoneResponse(result, input) {
         ...formatMaybe("Current Branch", result.currentBranch, 200),
         ...formatMaybe("Base Branch", result.baseBranch, 200),
         ...formatList("Criteria Checks", input.criteriaChecks, { maxItems: 10, maxItemChars: 220 }),
-        ...formatList("Constraints Checks", input.constraintsChecks ?? [], { maxItems: 10, maxItemChars: 220 }),
+        ...formatList("Rules Checks", input.rulesChecks ?? [], { maxItems: 10, maxItemChars: 220 }),
         `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),
     ];

package/build/workflow/round-summary.js

@@ -5,11 +5,11 @@ export const ROUND_SUMMARY_SECTION_KEYS = [
     "aestheticsGap",
     "blindspots",
     "criteriaCheck",
-    "constraintsCheck",
+    "rulesCheck",
 ];
 export const TOOL_DEFAULT_POLICY = Object.freeze({
     includeCriteriaCheck: false,
-    includeConstraintsCheck: false,
+    includeRulesCheck: false,
 });
 const SECTION_TITLE_TO_KEY = {
     outcome: "outcome",
@@ -17,7 +17,7 @@ const SECTION_TITLE_TO_KEY = {
     "aesthetics gap": "aestheticsGap",
     blindspots: "blindspots",
     "criteria check": "criteriaCheck",
-    "constraints check": "constraintsCheck",
+    "rules check": "rulesCheck",
 };
 function createEmptySections() {
     return {
@@ -26,7 +26,7 @@ function createEmptySections() {
         aestheticsGap: null,
         blindspots: null,
         criteriaCheck: null,
-        constraintsCheck: null,
+        rulesCheck: null,
     };
 }
 function normalizeTitle(value) {
@@ -62,8 +62,8 @@ function toKnownSection(sectionMarkdown) {
 function shouldRenderSection(key, policy) {
     if (key === "criteriaCheck")
         return policy.includeCriteriaCheck;
-    if (key === "constraintsCheck")
-        return policy.includeConstraintsCheck;
+    if (key === "rulesCheck")
+        return policy.includeRulesCheck;
     return true;
 }
 export function parseRoundSummary(raw) {

package/build/workflow/start.js

@@ -14,7 +14,7 @@ import { assertCleanWorkingTree } from "./contract.js";
 import { runAndRecordRound } from "./round.js";
 import { renderKeiyaku } from "./keiyaku-document-builder.js";
 import { normalizeDraftMarkdownListItems, parseAndValidateKeiyakuDraft, } from "./keiyaku-draft.js";
-const BASE_CONSTRAINTS_FILE = path.join(".keiyaku", "base-constraints.md");
+const BASE_RULES_FILE = path.join(".keiyaku", "base-rules.md");
 const ACTIVE_KEIYAKU_PREVIEW_MAX_CHARS = 8000;
 const INTERNAL_START_DIRTY_ALLOWLIST = [];
 function requireText(name, value) {
@@ -30,6 +30,9 @@ function normalizeOptionalText(value) {
     const normalized = value.trim();
     return normalized.length > 0 ? normalized : undefined;
 }
+function resolveFromFilePath(cwd, fromFile) {
+    return path.isAbsolute(fromFile) ? fromFile : path.join(cwd, fromFile);
+}
 function normalizeOptionalStringList(name, value) {
     if (value === undefined)
         return undefined;
@@ -137,7 +140,7 @@ async function resolveStartInput(cwd, input) {
         directive: normalizeOptionalText(input.directive),
         context: normalizeOptionalText(input.context),
         criteria: normalizeOptionalStringList("criteria", input.criteria),
-        constraints: normalizeOptionalStringList("constraints", input.constraints),
+        rules: normalizeOptionalStringList("rules", input.rules),
     };
     if (!fromFile) {
         if (!provided.title) {
@@ -158,12 +161,13 @@ async function resolveStartInput(cwd, input) {
             directive: provided.directive,
             context: provided.context,
             criteria: normalizeDraftMarkdownListItems("criteria", provided.criteria),
-            constraints: normalizeDraftMarkdownListItems("constraints", provided.constraints ?? []),
+            rules: normalizeDraftMarkdownListItems("rules", provided.rules ?? []),
             fromFile: undefined,
+            fromFilePath: undefined,
             dirtyAllowlist,
         };
     }
-    const draftPath = path.isAbsolute(fromFile) ? fromFile : path.join(cwd, fromFile);
+    const draftPath = resolveFromFilePath(cwd, fromFile);
     let content;
     try {
         content = await fs.readFile(draftPath, "utf-8");
@@ -180,7 +184,7 @@ async function resolveStartInput(cwd, input) {
     const directive = provided.directive ?? draft.directive;
     const context = provided.context ?? draft.context;
     const criteria = provided.criteria ?? draft.criteria;
-    const constraints = provided.constraints ?? draft.constraints ?? [];
+    const rules = provided.rules ?? draft.rules ?? [];
     if (!title) {
         throw new FlowError("INVALID_KEIYAKU_DRAFT", "invalid keiyaku draft: missing required field 'title'");
     }
@@ -199,15 +203,16 @@ async function resolveStartInput(cwd, input) {
         directive,
         context,
         criteria: normalizeDraftMarkdownListItems("criteria", criteria),
-        constraints: normalizeDraftMarkdownListItems("constraints", constraints),
+        rules: normalizeDraftMarkdownListItems("rules", rules),
         fromFile,
+        fromFilePath: draftPath,
         dirtyAllowlist,
     };
 }
-async function readBaseConstraints(cwd) {
+async function readBaseRules(cwd) {
     try {
-        const baseConstraintsRaw = await fs.readFile(path.join(cwd, BASE_CONSTRAINTS_FILE), "utf-8");
-        return flattenMarkdownList(baseConstraintsRaw);
+        const baseRulesRaw = await fs.readFile(path.join(cwd, BASE_RULES_FILE), "utf-8");
+        return flattenMarkdownList(baseRulesRaw);
     }
     catch (error) {
         if (error?.code !== "ENOENT") {
@@ -217,8 +222,8 @@ async function readBaseConstraints(cwd) {
     }
 }
 async function renderStartKeiyakuContent(cwd, resolved) {
-    const baseConstraints = await readBaseConstraints(cwd);
-    return renderKeiyaku(resolved.title, resolved.goal, resolved.context, baseConstraints, resolved.constraints, resolved.criteria);
+    const baseRules = await readBaseRules(cwd);
+    return renderKeiyaku(resolved.title, resolved.goal, resolved.context, baseRules, resolved.rules, resolved.criteria);
 }
 async function rollbackBranchCreation(cwd, keiyakuBranch, baseBranch) {
     try {
@@ -239,39 +244,60 @@ async function rollbackBranchCreation(cwd, keiyakuBranch, baseBranch) {
 }
 async function handleStartFailure(cwd, error, keiyakuContent, fromFile) {
     let savedDraft = false;
+    let replacedExistingDraft = false;
+    let draftSaveFailed;
     // Only attempt to save draft if user didn't start from a file.
     if (keiyakuContent && !fromFile) {
         try {
             const draftPath = path.join(cwd, KEIYAKU_DRAFT_FILE);
-            if (await fileExists(draftPath)) {
-                if (shouldEmitProgressLogs())
-                    console.warn("[keiyaku] Race condition: Draft file exists. Content not saved.");
+            const draftExists = await fileExists(draftPath);
+            await fs.writeFile(draftPath, keiyakuContent);
+            replacedExistingDraft = draftExists;
+            if (draftExists && shouldEmitProgressLogs()) {
+                console.warn(`[keiyaku] Existing ${KEIYAKU_DRAFT_FILE} was replaced with the latest failed start draft.`);
             }
-            else {
-                await fs.writeFile(draftPath, keiyakuContent, { flag: "wx" });
-                const startToolName = resolveTermPreset().tools.start.name;
-                if (shouldEmitProgressLogs()) {
-                    console.error(`[keiyaku] Start failed. Draft saved to ${KEIYAKU_DRAFT_FILE}. Retry with: ${startToolName} --from_file ${KEIYAKU_DRAFT_FILE}`);
-                }
-                savedDraft = true;
+            const startToolName = resolveTermPreset().tools.start.name;
+            if (shouldEmitProgressLogs()) {
+                console.error(`[keiyaku] Start failed. Draft saved to ${KEIYAKU_DRAFT_FILE}. Retry with: ${startToolName} --from_file ${KEIYAKU_DRAFT_FILE}`);
             }
+            savedDraft = true;
         }
         catch (draftSaveError) {
             const message = draftSaveError instanceof Error ? draftSaveError.message : String(draftSaveError);
+            draftSaveFailed = message;
             if (shouldEmitProgressLogs())
                 console.error(`[keiyaku] Failed to save draft file: ${message}`);
         }
     }
     if (savedDraft) {
-        const retryHint = `Draft saved to ${KEIYAKU_DRAFT_FILE}. Retry with from_file: ${KEIYAKU_DRAFT_FILE}`;
+        const draftReplacedWarning = `Existing ${KEIYAKU_DRAFT_FILE} was replaced with the latest failed start draft`;
+        const retryHint = replacedExistingDraft
+            ? `${draftReplacedWarning}. Draft saved to ${KEIYAKU_DRAFT_FILE}. Retry with from_file: ${KEIYAKU_DRAFT_FILE}`
+            : `Draft saved to ${KEIYAKU_DRAFT_FILE}. Retry with from_file: ${KEIYAKU_DRAFT_FILE}`;
         if (isFlowError(error)) {
-            throw wrapFlowError("start keiyaku", new FlowError(error.code, `${error.message}\n\n${retryHint}`, error));
+            throw wrapFlowError("start keiyaku", new FlowError(error.code, `${error.message}\n\n${retryHint}`, {
+                cause: error,
+                suggestion: retryHint,
+            }));
         }
         if (error instanceof Error) {
             throw wrapFlowError("start keiyaku", new Error(`${error.message}\n\n${retryHint}`, { cause: error }));
         }
         throw wrapFlowError("start keiyaku", new Error(`${String(error)}\n\n${retryHint}`));
     }
+    if (draftSaveFailed) {
+        const draftSaveHint = `Failed to save ${KEIYAKU_DRAFT_FILE}: ${draftSaveFailed}`;
+        if (isFlowError(error)) {
+            throw wrapFlowError("start keiyaku", new FlowError(error.code, `${error.message}\n\n${draftSaveHint}`, {
+                cause: error,
+                suggestion: draftSaveHint,
+            }));
+        }
+        if (error instanceof Error) {
+            throw wrapFlowError("start keiyaku", new Error(`${error.message}\n\n${draftSaveHint}`, { cause: error }));
+        }
+        throw wrapFlowError("start keiyaku", new Error(`${String(error)}\n\n${draftSaveHint}`));
+    }
     throw wrapFlowError("start keiyaku", error);
 }
 export async function startKeiyaku(input) {
@@ -281,6 +307,8 @@ export async function startKeiyaku(input) {
     let createdBranch = false;
     let keiyakuBranch;
     let baseBranch;
+    let consumedFromFile;
+    let existingBranches;
     try {
         // Eagerly render content to enable draft recovery on early failures.
         keiyakuContent = await renderStartKeiyakuContent(cwd, resolved);
@@ -292,9 +320,10 @@ export async function startKeiyaku(input) {
         if (existingKeiyaku) {
             throw new FlowError("ACTIVE_KEIYAKU_EXISTS", await buildActiveKeiyakuStartMessage(cwd, existingKeiyaku));
         }
-        const existingBranches = await git.listLocalKeiyakuBranches(cwd);
-        if (existingBranches.length > 0) {
-            const branchWarning = `[keiyaku] existing local keiyaku branches detected (non-blocking): ${existingBranches.join(", ")}`;
+        const existingKeiyakuBranches = await git.listLocalKeiyakuBranches(cwd);
+        if (existingKeiyakuBranches.length > 0) {
+            existingBranches = existingKeiyakuBranches;
+            const branchWarning = `[keiyaku] existing local keiyaku branches detected (non-blocking): ${existingKeiyakuBranches.join(", ")}`;
             if (shouldEmitProgressLogs())
                 console.error(branchWarning);
             appendDebugLog(branchWarning, { cwd, section: "script" });
@@ -322,7 +351,7 @@ export async function startKeiyaku(input) {
             keiyakuContent = await renderStartKeiyakuContent(cwd, resolved);
         }
         const parsedKeiyaku = parseMarkdownStructure(keiyakuContent);
-        const constraintsSection = parsedKeiyaku.sections.get("constraints")?.join("\n").trim() ?? "";
+        const rulesSection = parsedKeiyaku.sections.get("rules")?.join("\n").trim() ?? "";
         await fs.writeFile(path.join(cwd, KEIYAKU_FILE), keiyakuContent);
         await fs.writeFile(path.join(cwd, TRACE_FILE), "# Keiyaku Trace\n");
         await git.addFiles(cwd, [KEIYAKU_FILE, TRACE_FILE]);
@@ -336,12 +365,21 @@ export async function startKeiyaku(input) {
         });
         const summary = renderRoundSummary(roundSummary, TOOL_DEFAULT_POLICY);
         const diff = await git.getIncrementalDiff(cwd);
+        if (resolved.fromFile && resolved.fromFilePath) {
+            await fs.unlink(resolved.fromFilePath);
+            consumedFromFile = resolved.fromFile;
+            if (shouldEmitProgressLogs()) {
+                console.error(`[keiyaku] Consumed from_file and deleted source draft: ${resolved.fromFile}`);
+            }
+        }
         return {
             status: "success",
             round: 1,
             diff,
             summary,
-            constraints: constraintsSection,
+            rules: rulesSection,
+            consumedFromFile,
+            existingBranches,
             currentBranch: keiyakuBranch,
             baseBranch,
             commit,

package/package.json

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