@astrosheep/keiyaku 0.1.3 → 0.1.5

package/build/common/errors.js

@@ -28,92 +28,85 @@ export function wrapFlowError(action, err) {
     }
     return new Error(`${action} failed: ${asMessage(err)}`);
 }
-export function pickHintFromError(err, message) {
-    if (isFlowError(err)) {
-        switch (err.code) {
-            case "NOT_GIT_REPO":
-                return "The provided `cwd` is not a git repository.";
-            case "ACTIVE_KEIYAKU_EXISTS":
-                return "An active keiyaku branch already exists in this repository.";
-            case "EXISTING_KEIYAKU_BRANCH_FOUND":
-                return "At least one local `keiyaku/*` branch already exists in this repository.";
-            case "EMPTY_PARAM":
-                return "One or more required parameters are empty.";
-            case "DIRTY_WORKTREE":
-                return "The working tree has uncommitted changes.";
-            case "NOT_ACTIVE_KEIYAKU_BRANCH":
-                return message;
-            case "MISSING_KEIYAKU_BASE":
-                return "Current keiyaku branch is missing `keiyakuBase` metadata.";
-            case "MISSING_PROTOCOL_FILES":
-                return "Required protocol files are missing (`KEIYAKU.md` or `KEIYAKU_TRACE.md`).";
-            case "DONE_MERGE_CONFLICT":
-                return "DONE encountered a git merge conflict.";
-            case "CLOSE_QUALITY_GATE_FAILED":
-                return "INVOKE was denied by Divine Judgment because one or more commandment thresholds or the minimum total score were not met.";
-            case "OATH_MISMATCH":
-                return err.message;
-            case "SUBAGENT_DID_NOT_ADVANCE_ROUND":
-                return "Subagent run did not append the expected new round in `KEIYAKU_TRACE.md`.";
-            case "ROUND_SUBAGENT_FAILED":
-                return "Subagent execution failed. Review KEIYAKU_TRACE.md for details, then continue with a narrower directive.";
-            case "INVALID_BRANCH_TITLE":
-                return "Title cannot be converted to a valid branch token for `keiyaku/<title>`.";
-            case "UNKNOWN_SUBAGENT":
-                return unknownSubagentHint();
-            default:
-                return "Review the error details, fix the issue, and retry.";
-        }
-    }
-    // Fallback for untyped runtime errors.
-    if (message.includes("is not a git repository")) {
-        return "The provided `cwd` is not a git repository.";
-    }
-    if (message.includes("active keiyaku already exists")) {
-        return "An active keiyaku branch already exists in this repository.";
-    }
-    if (message.includes("existing keiyaku branch found")) {
-        return "At least one local `keiyaku/*` branch already exists in this repository.";
-    }
-    if (message.includes("parameter") && message.includes("cannot be empty")) {
-        return "One or more required parameters are empty.";
-    }
-    if (message.includes("working tree has uncommitted changes")) {
-        return "The working tree has uncommitted changes.";
-    }
-    if (message.includes("current branch is not an active keiyaku branch")) {
-        return "No active keiyaku branch (`keiyaku/*`). If this task is not using keiyaku workflow, skip this tool call.";
-    }
-    if (message.includes("is missing base metadata")) {
-        return "Current keiyaku branch is missing `keiyakuBase` metadata.";
+function hintForFlowCode(code, message) {
+    switch (code) {
+        case "NOT_GIT_REPO":
+            return "The provided `cwd` is not a git repository.";
+        case "ACTIVE_KEIYAKU_EXISTS":
+            return "An active keiyaku branch already exists in this repository. Continue with `drive`, or use `close` + `ABANDON` to drop it.";
+        case "EXISTING_KEIYAKU_BRANCH_FOUND":
+            return "At least one local `keiyaku/*` branch already exists in this repository.";
+        case "EMPTY_PARAM":
+            return "One or more required parameters are empty.";
+        case "DIRTY_WORKTREE":
+            return "The working tree has uncommitted changes.";
+        case "NOT_ACTIVE_KEIYAKU_BRANCH":
+            return message;
+        case "MISSING_KEIYAKU_BASE":
+            return "Current keiyaku branch is missing `keiyakuBase` metadata.";
+        case "MISSING_PROTOCOL_FILES":
+            return "Required protocol files are missing (`KEIYAKU.md` or `KEIYAKU_TRACE.md`).";
+        case "DONE_MERGE_CONFLICT":
+            return "DONE encountered a git merge conflict.";
+        case "CLOSE_QUALITY_GATE_FAILED":
+            return "INVOKE was denied by Divine Judgment because one or more commandment thresholds or the minimum total score were not met.";
+        case "OATH_MISMATCH":
+            return message;
+        case "SUBAGENT_DID_NOT_ADVANCE_ROUND":
+            return "Subagent run did not append the expected new round in `KEIYAKU_TRACE.md`.";
+        case "ROUND_SUBAGENT_FAILED":
+            return "Subagent execution failed. Review KEIYAKU_TRACE.md for details, then continue with a narrower directive.";
+        case "INVALID_BRANCH_TITLE":
+            return "Title cannot be converted to a valid branch token for `keiyaku/<title>`.";
+        case "UNKNOWN_SUBAGENT":
+            return unknownSubagentHint();
     }
-    if (message.includes("missing protocol files")) {
-        return "Required protocol files are missing (`KEIYAKU.md` or `KEIYAKU_TRACE.md`).";
-    }
-    if (message.includes("DONE merge conflict")) {
-        return "DONE encountered a git merge conflict.";
-    }
-    if (message.includes("God's Wrath: INVOKE denied")) {
-        return "INVOKE was denied by Divine Judgment because one or more commandment thresholds or the minimum total score were not met.";
-    }
-    if (message.includes("requires the sacred oath to exactly equal") ||
-        message.includes("requires oath to exactly match configured value") ||
-        message.includes("requires oath to match configured value. If template contains") ||
-        message.includes("To declare DONE, you must solemnly swear the sacred oath.") ||
-        message.includes("To declare DONE, oath mismatch.")) {
-        return message;
-    }
-    if (message.includes("subagent did not advance round") || message.includes("did not append KEIYAKU_TRACE")) {
-        return "Subagent run did not append the expected new round in `KEIYAKU_TRACE.md`.";
-    }
-    if (message.includes("failed during subagent execution")) {
-        return "Subagent execution failed. Review KEIYAKU_TRACE.md for details, then continue with a narrower directive.";
+}
+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: INVOKE 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"] },
+];
+function inferFlowCodeFromMessage(message) {
+    for (const entry of MESSAGE_HINT_PATTERNS) {
+        if (entry.patterns.some((pattern) => message.includes(pattern))) {
+            return entry.code;
+        }
     }
-    if (message.includes("cannot be converted to a valid branch name")) {
-        return "Title cannot be converted to a valid branch token for `keiyaku/<title>`.";
+    return null;
+}
+export function pickHintFromError(err, message) {
+    if (isFlowError(err)) {
+        return hintForFlowCode(err.code, err.message);
     }
-    if (message.includes("Unknown subagent")) {
-        return unknownSubagentHint();
+    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

@@ -52,37 +52,37 @@ export const DEFAULT_PRESET = {
         start: {
             name: 'summon',
             title: 'Sign Keiyaku',
-            description: 'Sign the Keiyaku. Creates a dedicated branch, locks in the mission, and initiates the iterative loop.\nCall ONCE per task to start the cycle. Workspace must be clean.\nBefore signing, define the kill condition clearly. If the target is blurry, use ask to scout first.\n\nFlow: summon → [drive x N] → request_verdict',
+            description: 'Sign the Keiyaku and assign the mission to a servant. This creates a dedicated branch where the servant will labor until the goal is met.\nCall ONCE per task to start the cycle. Workspace must be clean.\n\nFlow: summon → [drive x N] → request_verdict',
             args: {
                 title: 'REQUIRED. A concise codename for this hunt.',
-                goal: 'REQUIRED. The Kill Condition. State exactly what success looks like in the code.',
-                directive: 'Optional Round 1 Focus. Use for complex hunts to leash the servant to a specific starting point. Skip for simple tasks.',
-                context: 'REQUIRED. Mission Intel. The complete knowledge base: current vs. expected behavior, relevant file paths, error logs, and any critical background info.',
+                goal: 'REQUIRED. The Kill Condition. State exactly what success looks like for the servant to achieve.',
+                directive: 'Optional Round 1 Focus. Use to leash the servant to a specific starting point. Skip for simple tasks.',
+                context: 'REQUIRED. Mission Intel. The complete knowledge base for the servant: current vs. expected behavior, relevant file paths, error logs, and any critical background info.',
                 constraints: 'REQUIRED. Non-negotiable Rules. Architectural and stylistic boundaries the servant must obey.',
-                criteria: 'REQUIRED. Acceptance Criteria. Verifiable checks to prove the job is done.',
-                name: 'Optional ${IDENTITY} profile for this run. Presets: ${PRESET_IDENTITIES}.',
+                criteria: 'REQUIRED. Acceptance Criteria. Verifiable checks to prove the servant has finished the job.',
+                name: 'Optional ${IDENTITY} profile to execute this mission. Presets: ${PRESET_IDENTITIES}.',
                 cwd: "Optional repository path. Defaults to the server's current working directory.",
             },
         },
         drive: {
             name: 'drive',
             title: 'Iterate',
-            description: "Push the mission forward. Use this to issue the next command, whether it's correcting a mistake or advancing to the next phase of a complex kill.\nMANDATORY: Review the code (git diff) before iterating. Verify the last strike before ordering the next.\n\nFlow: summon → [drive x N] → request_verdict",
+            description: "Direct the active servant's next step. Provide feedback or new orders for the servant to implement in the current branch.\nMANDATORY: Review the servant's work (git diff) before iterating.\n\nFlow: summon → [drive x N] → request_verdict",
             args: {
-                directive: 'REQUIRED. The Next Order. Precise instructions for this round. Can be a correction ("fix the leak") or a continuation ("now add the tests").',
-                context: 'Optional. New Intel. New error logs, discovered edge cases, or details for the next phase.',
-                name: 'Optional ${IDENTITY} profile for this round. Presets: ${PRESET_IDENTITIES}.',
+                directive: 'REQUIRED. The Next Order. Precise instructions for the servant. Can be a correction ("fix the leak") or a continuation ("now add the tests").',
+                context: 'Optional. New Intel. New error logs or details discovered after the servant\'s last strike.',
+                name: 'Optional ${IDENTITY} profile to process this turn. Presets: ${PRESET_IDENTITIES}.',
                 cwd: "Optional repository path. Defaults to the server's current working directory.",
             },
         },
         ask: {
             name: 'ask',
             title: 'Ask',
-            description: 'Versatile, lightweight task runner. Use for investigative scouting, quick analysis, strategic consultation, or one-off executive tasks (like scripts or docs) that don\'t require the full keiyaku ceremony.\nResults and session logs are saved to .keiyaku/notes/.',
+            description: 'Delegate a quick task or analysis to a servant. Use for scouting, strategic consultation, or one-off tasks (like scripts or docs) where you want the servant to handle it without a full keiyaku.',
             args: {
-                request: 'REQUIRED. The question, analysis request, consultation topic, or tactical mission (e.g., "write a cleanup script").',
-                context: 'REQUIRED. Relevant background or data needed to execute the request.',
-                name: 'Optional ${IDENTITY} profile for this ask. Presets: ${PRESET_IDENTITIES}.',
+                request: 'REQUIRED. The task, question, or mission to delegate to the servant.',
+                context: 'REQUIRED. Relevant background or data the servant needs to execute the request.',
+                name: 'Optional ${IDENTITY} profile to perform this task. Presets: ${PRESET_IDENTITIES}.',
                 cwd: "Optional repository path. Defaults to the server's current working directory.",
             },
         },
@@ -93,11 +93,11 @@ export const DEFAULT_PRESET = {
             args: {
                 petition: 'REQUIRED. INVOKE begs acceptance; ABANDON confesses surrender.\nREQUIRES AN ACTIVE KEIYAKU (started via ${START_TOOL_NAME}).\nIf scores are weak, return to ${DRIVE_TOOL_NAME}.',
                 criteriaChecks: 'REQUIRED. Evidence for INVOKE, or explicit reasons for ABANDON.',
-                score_precise: 'REQUIRED score (0-5). 5 means the change lands exactly in the rightful architectural location.',
-                score_minimal: 'REQUIRED score (0-5). 5 means no excess diff beyond necessity.',
-                score_isolated: 'REQUIRED score (0-5). 5 means unrelated work is absent.',
-                score_idiomatic: 'REQUIRED score (0-5). 5 means naming and structure honor repository conventions.',
-                score_cohesive: 'REQUIRED score (0-5). 5 means responsibilities are clear and boundaries are pure.',
+                score_precise: 'REQUIRED score (0-5). 5 means architecturally flawless placement: exact layer, exact boundary, zero meaningful misplacement risk.',
+                score_minimal: 'REQUIRED score (0-5). 5 means ruthlessly minimal: no avoidable lines, no speculative edits, no hidden bloat.',
+                score_isolated: 'REQUIRED score (0-5). 5 means surgically isolated: zero unrelated files, zero opportunistic cleanup, zero collateral change.',
+                score_idiomatic: 'REQUIRED score (0-5). 5 means idiomatically perfect: naming, structure, and style are native-quality with no visible friction.',
+                score_cohesive: 'REQUIRED score (0-5). 5 means cohesion is pristine: each unit has one clear responsibility and boundaries are uncompromised.',
                 oath: 'Sacred confession text. Required for INVOKE. Verbatim: ${OATH_TEXT}',
                 cwd: "Optional repository path. Defaults to the server's current working directory.",
             },
@@ -189,11 +189,11 @@ export const POKEMON_PRESET = {
             args: {
                 petition: 'REQUIRED. INVOKE seeks blessing; ABANDON retreats in humility.\nREQUIRES AN ACTIVE BATTLE (started via ${START_TOOL_NAME}).\nIf scores are unworthy, continue with ${DRIVE_TOOL_NAME}.',
                 criteriaChecks: 'REQUIRED. Badge-by-badge proof for INVOKE, or confession for ABANDON.',
-                score_precise: 'REQUIRED score (0-5). 5 means each strike hit the intended layer perfectly.',
-                score_minimal: 'REQUIRED score (0-5). 5 means no unnecessary moves were used.',
-                score_isolated: 'REQUIRED score (0-5). 5 means no side-quests polluted this battle.',
-                score_idiomatic: "REQUIRED score (0-5). 5 means tactics match the team's doctrine.",
-                score_cohesive: 'REQUIRED score (0-5). 5 means each action held one clear purpose.',
+                score_precise: 'REQUIRED score (0-5). 5 means a flawless hit: exact layer, exact target, zero meaningful misplacement.',
+                score_minimal: 'REQUIRED score (0-5). 5 means perfectly efficient: no unnecessary moves, no extra motion, no bloat.',
+                score_isolated: 'REQUIRED score (0-5). 5 means pure battle focus: zero side-quests, zero unrelated damage.',
+                score_idiomatic: "REQUIRED score (0-5). 5 means doctrine-perfect execution: reads exactly like the team's strongest native style.",
+                score_cohesive: 'REQUIRED score (0-5). 5 means immaculate role clarity: each action serves one purpose with clean boundaries.',
                 oath: "Trainer's sacred confession. Required for INVOKE. Verbatim: ${OATH_TEXT}",
                 cwd: 'Optional battlefield path (repository root). Defaults to current arena.',
             },
@@ -285,11 +285,11 @@ export const MISCHIEF_PRESET = {
             args: {
                 petition: 'REQUIRED. INVOKE pleads for ascension; ABANDON confesses failure.\nREQUIRES AN ACTIVE SCHEME (started via ${START_TOOL_NAME}).\nIf scores are low, continue via ${DRIVE_TOOL_NAME}.',
                 criteriaChecks: 'REQUIRED. Proof of mastery for INVOKE, or explicit confession for ABANDON.',
-                score_precise: 'REQUIRED score (0-5). 5 means the strike landed in the ordained layer.',
-                score_minimal: 'REQUIRED score (0-5). 5 means no needless machinery was summoned.',
-                score_isolated: 'REQUIRED score (0-5). 5 means unrelated chaos stayed outside the diff.',
-                score_idiomatic: 'REQUIRED score (0-5). 5 means the code speaks native doctrine.',
-                score_cohesive: 'REQUIRED score (0-5). 5 means each unit bears one sacred duty.',
+                score_precise: 'REQUIRED score (0-5). 5 means ordained precision without flaw: exact layer, exact cut, zero meaningful drift.',
+                score_minimal: 'REQUIRED score (0-5). 5 means ascetic minimality: no needless machinery, no decorative motion, no excess.',
+                score_isolated: 'REQUIRED score (0-5). 5 means perfect containment: unrelated chaos remains fully outside this diff.',
+                score_idiomatic: 'REQUIRED score (0-5). 5 means native-tongue perfection: style and structure match house doctrine without strain.',
+                score_cohesive: 'REQUIRED score (0-5). 5 means sacred cohesion: each unit bears exactly one duty with uncompromised boundaries.',
                 oath: "Architect's sacred confession. Required for INVOKE. Verbatim: ${OATH_TEXT}",
                 cwd: 'Optional lair path (repository root). Defaults to current command chamber.',
             },

package/build/handlers/ask.js

@@ -1,9 +1,8 @@
 import { appendDebugLog } from "../utils/debug-log.js";
-import { asMessage, pickHintFromError } from "../common/errors.js";
 import { handleAsk } from "../workflow/orchestrator.js";
-import { buildAskResponse, buildToolErrorResponse, } from "../workflow/response-builders.js";
+import { buildAskResponse, } from "../workflow/response-builders.js";
 import { resolveTermPreset } from "../config/term-presets.js";
-import { classifyToolError } from "./shared.js";
+import { handleToolError } from "./shared.js";
 export function createAskHandler() {
     return async ({ request, context, name, cwd }, extra) => {
         const workingDir = cwd || process.cwd();
@@ -20,22 +19,16 @@ export function createAskHandler() {
             return buildAskResponse(result, { request, context, name, cwd: workingDir });
         }
         catch (err) {
-            const message = asMessage(err);
-            appendDebugLog(`tool ask error: ${message}`, { cwd: workingDir, section: "script" });
-            const hint = pickHintFromError(err, message);
-            const { errorType, errorCode } = classifyToolError(err);
-            const { identity } = resolveTermPreset();
-            return buildToolErrorResponse({
-                tool: "ask",
-                title: "Ask",
-                message,
-                hint,
-                errorType,
-                errorCode,
+            const preset = resolveTermPreset();
+            return handleToolError({
+                error: err,
+                toolName: preset.tools.ask.name,
+                cwd: workingDir,
+                logLabel: "tool ask",
                 inputEcho: [
                     `Request: ${request}`,
                     `Context: ${context}`,
-                    ...(name ? [`${identity}: ${name}`] : []),
+                    ...(name ? [`${preset.identity}: ${name}`] : []),
                     `CWD: ${workingDir}`,
                 ],
             });

package/build/handlers/close.js

@@ -1,9 +1,9 @@
 import { appendDebugLog } from "../utils/debug-log.js";
-import { asMessage, pickHintFromError } from "../common/errors.js";
 import { handleClose } from "../workflow/orchestrator.js";
-import { buildCloseDoneResponse, buildCloseDropResponse, buildToolErrorResponse, } from "../workflow/response-builders.js";
-import { classifyToolError } from "./shared.js";
-export function createCloseHandler(toolInfo) {
+import { buildCloseDoneResponse, buildCloseDropResponse, } from "../workflow/response-builders.js";
+import { resolveTermPreset } from "../config/term-presets.js";
+import { handleToolError } from "./shared.js";
+export function createCloseHandler() {
     return async ({ petition, criteriaChecks, score_precise, score_minimal, score_isolated, score_idiomatic, score_cohesive, oath, cwd, }, extra) => {
         const workingDir = cwd || process.cwd();
         const criteriaCheckParts = criteriaChecks;
@@ -64,17 +64,12 @@ export function createCloseHandler(toolInfo) {
             });
         }
         catch (err) {
-            const message = asMessage(err);
-            appendDebugLog(`tool close error: ${message}`, { cwd: workingDir, section: "script" });
-            const hint = pickHintFromError(err, message);
-            const { errorType, errorCode } = classifyToolError(err);
-            return buildToolErrorResponse({
-                tool: toolInfo.name,
-                title: toolInfo.title,
-                message,
-                hint,
-                errorType,
-                errorCode,
+            const preset = resolveTermPreset();
+            return handleToolError({
+                error: err,
+                toolName: preset.tools.close.name,
+                cwd: workingDir,
+                logLabel: "tool close",
                 inputEcho: [
                     `Petition: ${petition}`,
                     `Criteria checks (${criteriaCheckParts.length}): ${criteriaCheckParts.join("; ")}`,

package/build/handlers/drive.js

@@ -1,9 +1,8 @@
 import { appendDebugLog } from "../utils/debug-log.js";
-import { asMessage, pickHintFromError } from "../common/errors.js";
 import { handleDrive } from "../workflow/orchestrator.js";
-import { buildDriveResponse, buildToolErrorResponse, } from "../workflow/response-builders.js";
+import { buildDriveResponse, } from "../workflow/response-builders.js";
 import { resolveTermPreset } from "../config/term-presets.js";
-import { classifyToolError } from "./shared.js";
+import { handleToolError } from "./shared.js";
 export function createDriveHandler() {
     return async ({ directive, context, name, cwd }, extra) => {
         const workingDir = cwd || process.cwd();
@@ -26,22 +25,16 @@ export function createDriveHandler() {
             return buildDriveResponse(outcome, { directive, context, name, cwd: workingDir });
         }
         catch (err) {
-            const message = asMessage(err);
-            appendDebugLog(`tool drive error: ${message}`, { cwd: workingDir, section: "script" });
-            const hint = pickHintFromError(err, message);
-            const { errorType, errorCode } = classifyToolError(err);
-            const { identity } = resolveTermPreset();
-            return buildToolErrorResponse({
-                tool: "drive",
-                title: "Drive",
-                message,
-                hint,
-                errorType,
-                errorCode,
+            const preset = resolveTermPreset();
+            return handleToolError({
+                error: err,
+                toolName: preset.tools.drive.name,
+                cwd: workingDir,
+                logLabel: "tool drive",
                 inputEcho: [
                     `Directive: ${directive}`,
                     ...(context ? [`Context: ${context}`] : []),
-                    ...(name ? [`${identity}: ${name}`] : []),
+                    ...(name ? [`${preset.identity}: ${name}`] : []),
                     `CWD: ${workingDir}`,
                 ],
             });

package/build/handlers/help.js

@@ -1,28 +1,8 @@
-import * as git from '../utils/git.js';
 export function createHelpHandler(preset) {
     return async ({ question }) => {
-        const workingDir = process.cwd();
-        let branchState = 'Unknown';
-        try {
-            const currentBranch = await git.getCurrentBranch(workingDir);
-            const activeKeiyaku = await git.getActiveKeiyakuBranch(workingDir);
-            if (activeKeiyaku) {
-                const base = await git.getKeiyakuBase(workingDir, activeKeiyaku);
-                branchState = `Active Keiyaku: ${activeKeiyaku}\n  Base Branch: ${base || 'unknown'}`;
-            }
-            else {
-                branchState = `No active keiyaku. Current branch: ${currentBranch}`;
-            }
-        }
-        catch {
-            branchState = 'Not a git repository or git error.';
-        }
         const helpContent = [
             '# Keiyaku System Help',
             '',
-            '## Current State',
-            branchState,
-            '',
             '## Core Files (.keiyaku/)',
             "These files define the 'Law' of the project. **CRITICAL**: Use Markdown level 2 headers (## header).",
             '',
@@ -39,7 +19,7 @@ export function createHelpHandler(preset) {
         ].join('\n');
         return {
             content: [{ type: 'text', text: helpContent }],
-            structuredContent: { tool: 'cli_help', status: 'success' },
+            structuredContent: { tool: preset.tools.help.name, status: 'success' },
         };
     };
 }

package/build/handlers/shared.js

@@ -1,5 +1,7 @@
 import { isSubagentExecError } from "../agents/index.js";
-import { isFlowError } from "../common/errors.js";
+import { asMessage, isFlowError, pickHintFromError } from "../common/errors.js";
+import { appendDebugLog } from "../utils/debug-log.js";
+import { buildToolErrorResponse } from "../workflow/response-builders.js";
 export function classifyToolError(error) {
     if (isFlowError(error)) {
         return { errorType: "keiyaku_error", errorCode: error.code };
@@ -12,3 +14,17 @@ export function classifyToolError(error) {
     }
     return { errorType: "runtime_error", errorCode: "INTERNAL_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 { errorType, errorCode } = classifyToolError(input.error);
+    return buildToolErrorResponse({
+        tool: input.toolName,
+        message,
+        hint,
+        errorType,
+        errorCode,
+        inputEcho: input.inputEcho,
+    });
+}

package/build/handlers/start.js

@@ -1,25 +1,20 @@
 import { appendDebugLog } from "../utils/debug-log.js";
-import { asMessage, pickHintFromError } from "../common/errors.js";
 import { handleStart } from "../workflow/orchestrator.js";
-import { buildKeiyakuSuccessResponse, buildToolErrorResponse, } from "../workflow/response-builders.js";
+import { buildKeiyakuSuccessResponse, } from "../workflow/response-builders.js";
 import { resolveTermPreset } from "../config/term-presets.js";
-import { classifyToolError } from "./shared.js";
-function formatCriteria(criteria) {
-    return criteria.map((item) => `- ${item}`).join("\n");
-}
-export function createStartHandler(toolName) {
+import { handleToolError } from "./shared.js";
+export function createStartHandler() {
     return async ({ title, goal, directive, context, constraints, criteria, name, cwd }, extra) => {
         const workingDir = cwd || process.cwd();
         try {
             appendDebugLog(`tool start cwd=${workingDir}`, { cwd: workingDir, section: "script" });
-            const finalContext = context?.trim() || "No additional context provided.";
             const result = await handleStart({
                 cwd: workingDir,
                 title,
                 goal,
                 directive,
-                context: finalContext,
-                criteria: formatCriteria(criteria),
+                context,
+                criteria,
                 constraints,
                 name,
                 signal: extra.signal,
@@ -40,18 +35,12 @@ export function createStartHandler(toolName) {
             });
         }
         catch (err) {
-            const message = asMessage(err);
-            appendDebugLog(`tool start error: ${message}`, { cwd: workingDir, section: "script" });
-            const hint = pickHintFromError(err, message);
-            const { errorType, errorCode } = classifyToolError(err);
-            const { identity } = resolveTermPreset();
-            return buildToolErrorResponse({
-                tool: toolName,
-                title: "Keiyaku",
-                message,
-                hint,
-                errorType,
-                errorCode,
+            const preset = resolveTermPreset();
+            return handleToolError({
+                error: err,
+                toolName: preset.tools.start.name,
+                cwd: workingDir,
+                logLabel: "tool start",
                 inputEcho: [
                     `Title: ${title}`,
                     `Goal: ${goal}`,
@@ -59,7 +48,7 @@ export function createStartHandler(toolName) {
                     `Criteria (${criteria.length}): ${criteria.join("; ")}`,
                     ...(context ? [`Context: ${context}`] : []),
                     ...(constraints ? [`Constraints: ${constraints}`] : []),
-                    ...(name ? [`${identity}: ${name}`] : []),
+                    ...(name ? [`${preset.identity}: ${name}`] : []),
                     `CWD: ${workingDir}`,
                 ],
             });

package/build/index.js

@@ -62,7 +62,7 @@ function registerTools(server) {
         title: startPreset.title,
         description: dynamicStartDescription,
         inputSchema: dynamicStartSchema,
-    }, createStartHandler(startPreset.name));
+    }, createStartHandler());
     server.registerTool(drivePreset.name, {
         title: drivePreset.title,
         description: dynamicDriveDescription,
@@ -77,10 +77,7 @@ function registerTools(server) {
         title: closePreset.title,
         description: dynamicCloseDescription,
         inputSchema: dynamicCloseSchema,
-    }, createCloseHandler({
-        name: closePreset.name,
-        title: closePreset.title,
-    }));
+    }, createCloseHandler());
     server.registerTool(helpPreset.name, {
         title: helpPreset.title,
         description: [dynamicHelpDescription, dynamicHelpUsageGuide].join("\n\n"),

package/build/types/tool-schemas.js

@@ -24,11 +24,11 @@ export const askToolSchema = z.object({
 export const closeToolSchema = z.object({
     petition: z.enum(["INVOKE", "ABANDON"]),
     criteriaChecks: z.array(z.string().trim().min(1)).min(1),
-    score_precise: z.number().int().min(0).max(5),
-    score_minimal: z.number().int().min(0).max(5),
-    score_isolated: z.number().int().min(0).max(5),
-    score_idiomatic: z.number().int().min(0).max(5),
-    score_cohesive: z.number().int().min(0).max(5),
+    score_precise: z.number().min(0).max(5),
+    score_minimal: z.number().min(0).max(5),
+    score_isolated: z.number().min(0).max(5),
+    score_idiomatic: z.number().min(0).max(5),
+    score_cohesive: z.number().min(0).max(5),
     oath: z.string().optional(),
     cwd: z.string().optional(),
 });

package/build/utils/git.js

@@ -362,8 +362,18 @@ export async function getIncrementalDiff(cwd) {
         ]);
     }
     catch (err) {
-        // If there's no HEAD~1 (e.g. first commit), fallback
-        return "No incremental diff available.";
+        const source = (err ?? {});
+        const text = [source.message, source.stderr, source.stdErr, source.stdout, source.stdOut]
+            .filter((value) => typeof value === "string" && value.length > 0)
+            .join("\n");
+        const isMissingBaseCommit = text.includes("bad revision") ||
+            text.includes("unknown revision or path not in the working tree") ||
+            text.includes("ambiguous argument");
+        if (isMissingBaseCommit) {
+            // If there's no HEAD~1 (e.g. first commit), fallback
+            return "No incremental diff available.";
+        }
+        throw wrapGitError(`diff --no-color --no-ext-diff --unified=3 ${range}`, err, cwd);
     }
     const sections = splitDiffByFile(rawPatch);
     if (sections.length === 0)

package/build/workflow/oath.js

@@ -1,4 +1,4 @@
-const DEFAULT_OATH = "I, [your name], solemnly swear that I have scrutinized this change line by line with my own eyes. This oath is handwritten as a testament to my responsibility. If logic fails where I claimed it sound, I shall bear the mark of this oversight forever.\n\nSigned: [your name]";
+const DEFAULT_OATH = "I, [your name], solemnly swear that I have scrutinized this change line by line with my own eyes. I further swear that every score I submit is fully objective, with no exaggeration whatsoever. This oath is handwritten as a testament to my responsibility. If logic fails where I claimed it sound, I shall bear the mark of this oversight forever.\n\nSigned: [your name]";
 const OATH_ENV_KEY = "KEIYAKU_CLOSE_OATH";
 const LEGACY_CLOSE_OATH_ENV_KEY = "KEIYAKU_JUDGMENT_OATH";
 const LEGACY_OATH_ENV_KEY = "KEIYAKU_SEAL_OATH";

package/build/workflow/orchestrator.js

@@ -36,6 +36,7 @@ const JUDGMENT_SETTINGS_FILE = path.join(".keiyaku", "settings.json");
 export { resolveOath };
 const BASE_CRITERIA_FILE = path.join(".keiyaku", "base-criteria.md");
 const BASE_CONSTRAINTS_FILE = path.join(".keiyaku", "base-constraints.md");
+const ACTIVE_KEIYAKU_PREVIEW_MAX_CHARS = 8000;
 function clampThreshold(value, fallback) {
     if (typeof value !== "number" || !Number.isFinite(value))
         return fallback;
@@ -52,6 +53,55 @@ function clampMinTotalScore(value, fallback) {
         return fallback;
     return candidate;
 }
+function truncateForMessage(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    return `${text.slice(0, maxChars)}\n...[truncated ${text.length - maxChars} chars]...`;
+}
+async function buildActiveKeiyakuStartMessage(cwd, branch) {
+    const lines = [
+        `active keiyaku already exists (${branch})`,
+        "This task is still active. Decide whether to continue or abandon it.",
+        "Continue: run drive on the current keiyaku branch.",
+        "Abandon: run close with petition=ABANDON to drop the branch.",
+    ];
+    try {
+        const keiyakuPath = path.join(cwd, KEIYAKU_FILE);
+        const keiyaku = await fs.readFile(keiyakuPath, "utf-8");
+        const preview = truncateForMessage(keiyaku.trim(), ACTIVE_KEIYAKU_PREVIEW_MAX_CHARS);
+        lines.push("", `[Current ${KEIYAKU_FILE}]`, preview || "(empty file)");
+    }
+    catch (error) {
+        if (error?.code === "ENOENT") {
+            lines.push("", `${KEIYAKU_FILE} not found on current branch.`);
+        }
+        else {
+            throw error;
+        }
+    }
+    try {
+        const trace = await readTraceContent(cwd);
+        const traceState = computeTraceState(trace);
+        if (traceState.pendingReviewRound !== null) {
+            lines.push(`Trace status: pending review ${traceState.pendingReviewRound}; latest completed round ${traceState.maxRound}.`);
+        }
+        else if (traceState.maxRound > 0) {
+            lines.push(`Trace status: completed through round ${traceState.maxRound}; no pending review.`);
+        }
+        else {
+            lines.push("Trace status: no completed rounds yet.");
+        }
+    }
+    catch (error) {
+        if (error?.code === "ENOENT") {
+            lines.push(`${TRACE_FILE} not found on current branch.`);
+        }
+        else {
+            throw error;
+        }
+    }
+    return lines.join("\n");
+}
 async function resolveJudgmentConfig(cwd) {
     const defaults = resolveTermPreset().divineJudgment;
     const merged = {
@@ -239,9 +289,14 @@ export async function handleStart(input) {
     const finalTitle = requireText("title", input.title);
     const finalGoal = requireText("goal", input.goal);
     const finalContext = requireText("context", input.context);
-    const finalCriteria = requireText("criteria", input.criteria);
-    const taskCriteria = parseMarkdownHeaders(finalCriteria);
-    const normalizedTaskCriteria = taskCriteria.length > 0 ? taskCriteria : [finalCriteria];
+    if (input.criteria.length === 0) {
+        throw new FlowError("EMPTY_PARAM", "parameter 'criteria' cannot be empty");
+    }
+    const normalizedTaskCriteria = input.criteria.flatMap((criterion, index) => {
+        const normalizedCriterion = requireText(`criteria[${index}]`, criterion);
+        const parsed = parseMarkdownHeaders(normalizedCriterion);
+        return parsed.length > 0 ? parsed : [normalizedCriterion];
+    });
     const finalConstraints = input.constraints?.trim();
     const taskConstraints = finalConstraints ? parseMarkdownHeaders(finalConstraints) : [];
     const normalizedTaskConstraints = finalConstraints && taskConstraints.length > 0 ? taskConstraints : finalConstraints ? [finalConstraints] : [];
@@ -252,7 +307,7 @@ export async function handleStart(input) {
     }
     const existingKeiyaku = await git.getActiveKeiyakuBranch(cwd);
     if (existingKeiyaku) {
-        throw new FlowError("ACTIVE_KEIYAKU_EXISTS", `active keiyaku already exists (${existingKeiyaku}); close or drop it first`);
+        throw new FlowError("ACTIVE_KEIYAKU_EXISTS", await buildActiveKeiyakuStartMessage(cwd, existingKeiyaku));
     }
     const existingBranches = await git.listLocalKeiyakuBranches(cwd);
     if (existingBranches.length > 0) {
@@ -306,7 +361,6 @@ export async function handleStart(input) {
         });
         const trace = await fs.readFile(path.join(cwd, TRACE_FILE), "utf-8");
         const diff = await git.getIncrementalDiff(cwd);
-        const content = `Round ${1} complete on ${keiyakuBranch}.`;
         return {
             status: "success",
             round: 1,
@@ -315,7 +369,6 @@ export async function handleStart(input) {
             summary,
             branch: keiyakuBranch,
             baseBranch,
-            content,
         };
     }
     catch (err) {
@@ -365,6 +418,14 @@ export async function handleClose(input) {
     const title = keiyakuBranch.slice("keiyaku/".length);
     const petition = input.petition;
     if (petition === "ABANDON") {
+        let round = 0;
+        try {
+            const trace = await fs.readFile(path.join(cwd, TRACE_FILE), "utf-8");
+            round = computeTraceState(trace).maxRound;
+        }
+        catch {
+            round = 0;
+        }
         await assertCleanWorkingTree(cwd);
         try {
             await git.checkoutBranch(cwd, baseBranch);
@@ -374,14 +435,6 @@ export async function handleClose(input) {
         catch (err) {
             throw wrapFlowError(`execute ABANDON (${keiyakuBranch} -> ${baseBranch})`, err);
         }
-        let round = 0;
-        try {
-            const trace = await fs.readFile(path.join(cwd, TRACE_FILE), "utf-8");
-            round = computeTraceState(trace).maxRound;
-        }
-        catch {
-            round = 0;
-        }
         return {
             status: "success",
             result: "dropped",
@@ -389,7 +442,6 @@ export async function handleClose(input) {
             branch: keiyakuBranch,
             baseBranch,
             diff: "Abandoned without merge.",
-            content: `Abandoned ${keiyakuBranch}.`,
         };
     }
     await ensureKeiyakuFiles(cwd);
@@ -461,7 +513,6 @@ export async function handleClose(input) {
                 branch: keiyakuBranch,
                 baseBranch,
                 diff,
-                content: `Merged ${keiyakuBranch} into ${baseBranch}.`,
             };
         }
         catch (err) {
@@ -510,7 +561,6 @@ export async function handleDrive(input) {
         });
         const trace = await fs.readFile(path.join(cwd, TRACE_FILE), "utf-8");
         const diff = await git.getIncrementalDiff(cwd);
-        const content = `Round ${plan.targetRound} complete on ${keiyakuBranch}.`;
         return {
             status: "success",
             round: plan.targetRound,
@@ -519,7 +569,6 @@ export async function handleDrive(input) {
             summary,
             branch: keiyakuBranch,
             baseBranch,
-            content,
         };
     }
     catch (err) {

package/build/workflow/prompts.js

@@ -8,7 +8,7 @@ Round: 1 (initial implementation).
 - Directive: round scope.
 
 1. Read KEIYAKU.md. Use it as source of truth.
-2. If Focus exists, prioritize it.
+2. If Directive exists, prioritize it.
 3. Treat all constraints/criteria as required.
 4. Read KEIYAKU_TRACE.md if present.
 5. Execute:
@@ -38,7 +38,7 @@ Address this review reason:
 ${reason}
 
 1. Read KEIYAKU.md. Keep constraints/criteria unchanged.
-2. If Focus exists, prioritize it.
+2. If Directive exists, prioritize it.
 3. Read KEIYAKU_TRACE.md. Locate the latest "## Review ${round}" section.
 4. Fix review reason first.
 5. No drift from constraints/criteria.

package/build/workflow/response-builders.js

@@ -102,7 +102,6 @@ export function buildKeiyakuSuccessResponse(result, input) {
             nextHint: nextHints.join("\n"),
             inputEcho,
             ...result,
-            content: text,
         },
     };
 }
@@ -130,7 +129,6 @@ export function buildDriveResponse(result, input) {
             nextHint: nextHints.join("\n"),
             inputEcho,
             ...result,
-            content: text,
         },
     };
 }
@@ -183,7 +181,6 @@ export function buildCloseDoneResponse(result, input) {
             nextHint: nextHints.join("\n"),
             inputEcho,
             ...result,
-            content: text,
         },
     };
 }
@@ -211,12 +208,12 @@ export function buildCloseDropResponse(result, input) {
             nextHint: nextHints.join("\n"),
             inputEcho,
             ...result,
-            content: text,
         },
     };
 }
 export function buildToolErrorResponse(input) {
     const inputEcho = (input.inputEcho ?? []).map((line) => truncateForDisplay(line, 800));
+    const shouldRaiseProtocolError = input.errorType === "runtime_error";
     const text = assembleResponse("Failed", input.message, [buildSection("Input Context", inputEcho)], [input.hint]);
     return {
         content: [{ type: "text", text }],
@@ -229,6 +226,6 @@ export function buildToolErrorResponse(input) {
             hint: input.hint,
             inputEcho,
         },
-        isError: true,
+        ...(shouldRaiseProtocolError ? { isError: true } : {}),
     };
 }

package/package.json

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