@astrosheep/keiyaku 0.1.19 → 0.1.21

package/build/workflow/keiyaku-draft.js

@@ -0,0 +1,255 @@
+import { FlowError } from "../common/errors.js";
+import { extractListItems, parseToAST, renderSectionContent, } from "../utils/keiyaku-document.js";
+const KNOWN_DRAFT_SECTIONS = new Set([
+    "goal",
+    "directive",
+    "context",
+    "constraints",
+    "criteria",
+    "acceptance criteria",
+]);
+function normalizeSectionTitle(title) {
+    return title.trim().toLowerCase().replace(/\s+/g, " ");
+}
+function requireDraftText(name, value) {
+    const normalized = value.trim();
+    if (!normalized) {
+        throw new FlowError("EMPTY_PARAM", `parameter '${name}' cannot be empty`);
+    }
+    return normalized;
+}
+function parseFenceLine(trimmedLine) {
+    if (!trimmedLine.startsWith("```"))
+        return null;
+    let idx = 0;
+    while (idx < trimmedLine.length && trimmedLine[idx] === "`")
+        idx += 1;
+    if (idx < 3)
+        return null;
+    return idx;
+}
+function splitHeadingGroups(sectionNode) {
+    const firstMeaningful = sectionNode.children.find((child) => {
+        if (child.type !== "text")
+            return true;
+        return child.value.trim().length > 0;
+    });
+    if (!firstMeaningful || firstMeaningful.type !== "heading" || firstMeaningful.level < 2) {
+        return [];
+    }
+    const groups = [];
+    let currentChildren = [];
+    const commit = () => {
+        if (currentChildren.length === 0)
+            return;
+        groups.push({
+            type: "section",
+            level: 2,
+            title: "",
+            children: currentChildren,
+        });
+        currentChildren = [];
+    };
+    for (const child of sectionNode.children) {
+        if (child.type === "heading" && child.level >= 2) {
+            commit();
+            currentChildren = [child];
+            continue;
+        }
+        currentChildren.push(child);
+    }
+    commit();
+    return groups
+        .map((group) => renderSectionContent(group).trim())
+        .filter((item) => item.length > 0);
+}
+function collectSectionItems(ast, sectionTitle) {
+    const normalizedSectionTitle = normalizeSectionTitle(sectionTitle);
+    const targetSection = ast.children.find((node) => {
+        if (node.type !== "section")
+            return false;
+        if (node.level !== 2)
+            return false;
+        return normalizeSectionTitle(node.title) === normalizedSectionTitle;
+    });
+    if (!targetSection || targetSection.type !== "section") {
+        return [];
+    }
+    const listItems = extractListItems(targetSection);
+    if (listItems.length > 0) {
+        return listItems;
+    }
+    const grouped = splitHeadingGroups(targetSection);
+    if (grouped.length > 0) {
+        return grouped;
+    }
+    const content = renderSectionContent(targetSection).trim();
+    return content ? [content] : [];
+}
+function normalizeDraftHeadings(content) {
+    const lines = content.split(/\r?\n/);
+    if (lines.length > 0) {
+        lines[0] = lines[0].replace(/^\uFEFF/, "");
+    }
+    // Keep structural title/known section headings stable, and shift payload headings together.
+    const MIN_HEADING_LEVEL = 3;
+    let sawTitleH1 = false;
+    let fence = null;
+    let shallowestNonStructural = null;
+    for (const line of lines) {
+        let leadingSpaces = 0;
+        while (leadingSpaces < line.length && line[leadingSpaces] === " ")
+            leadingSpaces += 1;
+        const trimmed = leadingSpaces <= 3 ? line.trimStart() : line;
+        if (leadingSpaces <= 3) {
+            const fenceLen = parseFenceLine(trimmed);
+            if (fenceLen !== null) {
+                if (!fence)
+                    fence = { length: fenceLen };
+                else if (fenceLen >= fence.length)
+                    fence = null;
+                continue;
+            }
+        }
+        if (fence)
+            continue;
+        if (leadingSpaces > 3)
+            continue;
+        const headerMatch = trimmed.match(/^(#{1,6})[ \t]+(.+?)\s*$/);
+        if (!headerMatch)
+            continue;
+        const level = (headerMatch[1] ?? "").length;
+        const text = (headerMatch[2] ?? "").trim();
+        if (level === 1 && !sawTitleH1) {
+            sawTitleH1 = true;
+            continue;
+        }
+        if (level === 2) {
+            // Keep ALL H2 section headers structural in from_file drafts. Unknown headers
+            // should remain visible to validation instead of being silently demoted.
+            continue;
+        }
+        shallowestNonStructural = shallowestNonStructural === null ? level : Math.min(shallowestNonStructural, level);
+    }
+    if (shallowestNonStructural === null || shallowestNonStructural >= MIN_HEADING_LEVEL) {
+        return lines.join("\n");
+    }
+    const delta = MIN_HEADING_LEVEL - shallowestNonStructural;
+    const out = [];
+    sawTitleH1 = false;
+    fence = null;
+    for (const line of lines) {
+        let leadingSpaces = 0;
+        while (leadingSpaces < line.length && line[leadingSpaces] === " ")
+            leadingSpaces += 1;
+        const trimmed = leadingSpaces <= 3 ? line.trimStart() : line;
+        const prefix = line.slice(0, leadingSpaces);
+        if (leadingSpaces <= 3) {
+            const fenceLen = parseFenceLine(trimmed);
+            if (fenceLen !== null) {
+                if (!fence)
+                    fence = { length: fenceLen };
+                else if (fenceLen >= fence.length)
+                    fence = null;
+                out.push(line);
+                continue;
+            }
+        }
+        if (fence) {
+            out.push(line);
+            continue;
+        }
+        if (leadingSpaces <= 3) {
+            const headerMatch = trimmed.match(/^(#{1,6})[ \t]+(.+?)\s*$/);
+            if (headerMatch) {
+                const hashes = headerMatch[1] ?? "";
+                const text = (headerMatch[2] ?? "").trim();
+                const level = hashes.length;
+                if (level === 1) {
+                    if (!sawTitleH1) {
+                        sawTitleH1 = true;
+                        out.push(line);
+                        continue;
+                    }
+                    out.push(`${prefix}${"#".repeat(Math.min(6, level + delta))} ${text}`);
+                    continue;
+                }
+                if (level === 2) {
+                    out.push(line);
+                    continue;
+                }
+                out.push(`${prefix}${"#".repeat(Math.min(6, level + delta))} ${text}`);
+                continue;
+            }
+        }
+        out.push(line);
+    }
+    return out.join("\n");
+}
+export function normalizeDraftMarkdownListItems(name, values) {
+    const normalized = [];
+    for (const [index, value] of values.entries()) {
+        const normalizedValue = requireDraftText(`${name}[${index}]`, value);
+        const ast = parseToAST(normalizedValue, { allowSections: false });
+        const sectionNode = { type: "section", level: 2, title: "", children: ast.children };
+        const parsedItems = extractListItems(sectionNode);
+        if (parsedItems.length > 0) {
+            normalized.push(...parsedItems);
+            continue;
+        }
+        const grouped = splitHeadingGroups(sectionNode);
+        if (grouped.length > 0) {
+            normalized.push(...grouped);
+            continue;
+        }
+        const rendered = renderSectionContent(sectionNode).trim();
+        if (rendered.length > 0) {
+            normalized.push(rendered);
+            continue;
+        }
+        normalized.push(normalizedValue);
+    }
+    return normalized;
+}
+export function parseAndValidateKeiyakuDraft(content) {
+    const normalized = normalizeDraftHeadings(content);
+    const ast = parseToAST(normalized);
+    const sections = new Map();
+    let title;
+    for (const node of ast.children) {
+        if (node.type !== "section")
+            continue;
+        if (node.level === 1 && !title) {
+            title = node.title.trim() || undefined;
+            continue;
+        }
+        if (node.level !== 2)
+            continue;
+        const normalizedSection = normalizeSectionTitle(node.title);
+        if (sections.has(normalizedSection)) {
+            throw new FlowError("INVALID_KEIYAKU_DRAFT", `invalid keiyaku draft: duplicate section header '${normalizedSection}'`);
+        }
+        sections.set(normalizedSection, renderSectionContent(node).trim());
+    }
+    const unknownSections = [...sections.keys()].filter((section) => !KNOWN_DRAFT_SECTIONS.has(section));
+    if (unknownSections.length > 0) {
+        throw new FlowError("INVALID_KEIYAKU_DRAFT", `invalid keiyaku draft: unknown section header(s): ${unknownSections.map((section) => `'${section}'`).join(", ")}`);
+    }
+    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 criteria = sections.has("acceptance criteria")
+        ? collectSectionItems(ast, "acceptance criteria")
+        : sections.has("criteria")
+            ? collectSectionItems(ast, "criteria")
+            : undefined;
+    return {
+        title: title?.trim() || undefined,
+        goal: goal || undefined,
+        directive: directive || undefined,
+        context: context || undefined,
+        constraints: constraints && constraints.length > 0 ? constraints : undefined,
+        criteria: criteria && criteria.length > 0 ? criteria : undefined,
+    };
+}

package/build/workflow/present.js

@@ -1,8 +1,8 @@
 import * as fs from "fs/promises";
 import * as path from "path";
-import { KEIYAKU_DRAFT_FILE, KEIYAKU_DRAFT_NEW_FILE, KEIYAKU_FILE, TRACE_FILE } from "../common/constants.js";
+import { KEIYAKU_DRAFT_FILE, KEIYAKU_FILE, TRACE_FILE } from "../common/constants.js";
 import { resolveTermPreset } from "../config/term-presets.js";
-import { appendDebugLog } from "../utils/debug-log.js";
+import { appendDebugLog, shouldEmitProgressLogs } from "../utils/debug-log.js";
 import { FlowError, wrapFlowError } from "../common/errors.js";
 import * as git from "../utils/git.js";
 import { computeTraceState, readTraceContent } from "../utils/trace.js";
@@ -98,20 +98,6 @@ function requireChecks(name, 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}`;
@@ -134,6 +120,7 @@ export async function presentWork(input) {
     const petition = input.petition;
     if (petition === "FORFEIT") {
         let round = 0;
+        let preservedDraftContent;
         try {
             const trace = await fs.readFile(path.join(cwd, TRACE_FILE), "utf-8");
             round = computeTraceState(trace).maxRound;
@@ -141,6 +128,14 @@ export async function presentWork(input) {
         catch {
             round = 0;
         }
+        try {
+            preservedDraftContent = await fs.readFile(path.join(cwd, KEIYAKU_DRAFT_FILE), "utf-8");
+        }
+        catch (error) {
+            if (error?.code !== "ENOENT") {
+                throw error;
+            }
+        }
         const dirtyFiles = await git.getDirtyFiles(cwd);
         const droppedChanges = dirtyFiles.map((file) => `${file.index}${file.working_dir} ${file.path}`);
         try {
@@ -150,6 +145,22 @@ export async function presentWork(input) {
             await git.checkoutBranch(cwd, baseBranch);
             await git.deleteBranch(cwd, keiyakuBranch, true);
             await git.clearKeiyakuBase(cwd, keiyakuBranch);
+            if (preservedDraftContent !== undefined) {
+                const canonicalDraftPath = path.join(cwd, KEIYAKU_DRAFT_FILE);
+                try {
+                    // Restore as untracked recovery artifact on the base branch.
+                    await fs.writeFile(canonicalDraftPath, preservedDraftContent, { flag: "wx" });
+                }
+                catch (error) {
+                    if (error?.code === "EEXIST") {
+                        const fallbackDraftFile = "KEIYAKU.draft.forfeit.md";
+                        await fs.writeFile(path.join(cwd, fallbackDraftFile), preservedDraftContent, { flag: "wx" });
+                    }
+                    else {
+                        throw error;
+                    }
+                }
+            }
         }
         catch (err) {
             throw wrapFlowError(`execute FORFEIT (${keiyakuBranch} -> ${baseBranch})`, err);
@@ -197,35 +208,41 @@ export async function presentWork(input) {
         if (!oathMatches(input.oath, expectedOath)) {
             throw new FlowError("OATH_MISMATCH", `Oath mismatch. Correct oath: ${expectedOath}`);
         }
-        await assertCleanWorkingTree(cwd, [KEIYAKU_DRAFT_FILE, KEIYAKU_DRAFT_NEW_FILE]);
+        await assertCleanWorkingTree(cwd, [KEIYAKU_DRAFT_FILE]);
         try {
             const invokeDiffLog = `[CLAIM] Collecting diff preview against base '${baseBranch}'`;
-            console.error(invokeDiffLog);
+            if (shouldEmitProgressLogs())
+                console.error(invokeDiffLog);
             appendDebugLog(invokeDiffLog, { cwd, section: "script" });
             const invokeReadLog = "[CLAIM] Reading keiyaku protocol files";
-            console.error(invokeReadLog);
+            if (shouldEmitProgressLogs())
+                console.error(invokeReadLog);
             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);
+            if (shouldEmitProgressLogs())
+                console.error(invokeCleanupLog);
             appendDebugLog(invokeCleanupLog, { cwd, section: "script" });
             await removeClaimProtocolFiles(cwd);
-            await git.addFiles(cwd, "-A");
+            await git.addFiles(cwd, [KEIYAKU_FILE, TRACE_FILE]);
             await git.commit(cwd, `keiyaku(${title}): cleanup`);
             const invokeCheckoutLog = `[CLAIM] Checking out base branch '${baseBranch}'`;
-            console.error(invokeCheckoutLog);
+            if (shouldEmitProgressLogs())
+                console.error(invokeCheckoutLog);
             appendDebugLog(invokeCheckoutLog, { cwd, section: "script" });
             await git.checkoutBranch(cwd, baseBranch);
             const invokeMergeLog = `[CLAIM] Merging '${keiyakuBranch}' into '${baseBranch}'`;
-            console.error(invokeMergeLog);
+            if (shouldEmitProgressLogs())
+                console.error(invokeMergeLog);
             appendDebugLog(invokeMergeLog, { cwd, section: "script" });
             await git.merge(cwd, keiyakuBranch, message);
             const commit = await git.getLatestCommitHash(cwd);
             const invokeFinalizeLog = `[CLAIM] Deleting merged branch '${keiyakuBranch}' and clearing metadata`;
-            console.error(invokeFinalizeLog);
+            if (shouldEmitProgressLogs())
+                console.error(invokeFinalizeLog);
             appendDebugLog(invokeFinalizeLog, { cwd, section: "script" });
             await git.deleteBranch(cwd, keiyakuBranch, true);
             await git.clearKeiyakuBase(cwd, keiyakuBranch);

package/build/workflow/response-builders.js

@@ -200,8 +200,8 @@ export function buildCloseDoneResponse(result, input) {
         ...formatMaybe("Oath", input.oath, 220),
     ];
     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);
+        ? `Merged '${result.deletedBranch}' into '${result.mergedInto}' [${result.commit}]. Deleted feature branch. Note: KEIYAKU.draft.md preserved (if present).`
+        : `Merged '${result.deletedBranch}' into '${result.mergedInto}'. Deleted feature branch. Note: KEIYAKU.draft.md preserved (if present).`, [typeof diffSection === "string" ? null : diffSection].filter((section) => section !== null), infoLines);
     return {
         content: [{ type: "text", text }],
         structuredContent: buildSuccessStructuredContent(closeToolName, resultData),
@@ -219,8 +219,8 @@ export function buildCloseDropResponse(result, input) {
         ...formatMaybe("Base Branch", result.baseBranch, 200),
     ];
     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);
+        ? `Deleted '${result.deletedBranch}'. Switched back to '${result.baseBranch}'. Dropped ${droppedChanges.length} local change(s). Note: KEIYAKU.draft.md preserved (if present).`
+        : `Deleted '${result.deletedBranch}'. Switched back to '${result.baseBranch}'. Note: KEIYAKU.draft.md preserved (if present).`, [warningSection].filter((section) => section !== null), infoLines);
     return {
         content: [{ type: "text", text }],
         structuredContent: buildSuccessStructuredContent(closeToolName, resultData),

package/build/workflow/round.js

@@ -1,8 +1,8 @@
 import { selectSubagent } from "../agents/selector.js";
 import { describeSubagentFailure, runSubagent } from "../agents/round-runner.js";
-import { TRACE_FILE } from "../common/constants.js";
+import { KEIYAKU_DRAFT_FILE, TRACE_FILE } from "../common/constants.js";
 import { FlowError } from "../common/errors.js";
-import { appendDebugBlock, appendDebugLog } from "../utils/debug-log.js";
+import { appendDebugBlock, appendDebugLog, shouldEmitProgressLogs } from "../utils/debug-log.js";
 import * as git from "../utils/git.js";
 import { appendRoundReport } from "../utils/trace.js";
 import { parseRoundSummary } from "./round-summary.js";
@@ -46,6 +46,10 @@ async function appendRoundResult(cwd, round, summary, failureMessage) {
         filesModified,
     });
 }
+async function stageRoundCommit(cwd) {
+    // Never stage draft recovery artifacts; they should remain local unless explicitly committed by the user.
+    await git.addFiles(cwd, ["-A", "--", ".", `:(exclude)${KEIYAKU_DRAFT_FILE}`]);
+}
 export async function runAndRecordRound(cwd, titleToken, round, prompt, options) {
     const roundSubagent = selectSubagent(options.name);
     let rawSummary;
@@ -62,11 +66,13 @@ export async function runAndRecordRound(cwd, titleToken, round, prompt, options)
         }
         const failure = describeSubagentFailure(err, roundSubagent.displayName, round);
         const failureLog = `[Subagent failure] name=${failure.name} round=${failure.round} code=${failure.errorCode} timeoutMs=${failure.timeoutMs ?? "unknown"} exitCode=${failure.exitCode ?? "none"}`;
-        console.error(failureLog);
+        if (shouldEmitProgressLogs())
+            console.error(failureLog);
         appendDebugLog(failureLog, { cwd, section: "script" });
         if (failure.stderrSnippet) {
             const failureStderrLog = `[Subagent failure stderr]\n${failure.stderrSnippet}`;
-            console.error(failureStderrLog);
+            if (shouldEmitProgressLogs())
+                console.error(failureStderrLog);
             appendDebugBlock("subagent failure stderr", failure.stderrSnippet, { cwd, section: "codex-stderr" });
         }
         failureMessage = failure.message.trim() || "Unknown error.";
@@ -74,12 +80,12 @@ export async function runAndRecordRound(cwd, titleToken, round, prompt, options)
             ? `Round ${round} completed with subagent execution failure recorded in trace.`
             : "Round 1 completed with subagent execution failure recorded in trace.";
         await appendRoundResult(cwd, round, summary, failureMessage);
-        await git.addFiles(cwd, "-A");
+        await stageRoundCommit(cwd);
         await git.commit(cwd, `keiyaku(${titleToken}): round ${round}`);
         throw new FlowError("ROUND_SUBAGENT_FAILED", formatSubagentFailureMessage(failure), err);
     }
     await appendRoundResult(cwd, round, rawSummary);
-    await git.addFiles(cwd, "-A");
+    await stageRoundCommit(cwd);
     await git.commit(cwd, `keiyaku(${titleToken}): round ${round}`);
     return { roundSummary: parseRoundSummary(rawSummary) };
 }