deepclause-pi 0.3.0 → 0.5.0

package/dist/index.js

@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import { buildInitialMessages } from "./context.js";
-import { loadConfig, setModelToolEnabled } from "./config.js";
+import { loadConfig, setJudgeConfig, setModelToolEnabled } from "./config.js";
 import { renderDml, renderSequence } from "./diagram/extract.js";
 import { polishDiagram, resolveGrade } from "./diagram/grade.js";
 import { findChrome, validateMermaid } from "./diagram/validate.js";
@@ -68,10 +68,12 @@ export function parseRun(input) {
     let contextMode;
     let verbose = false;
     let debug = false;
+    let judge;
     const args = [];
     for (let index = 0; index < tokens.length; index++) {
         const token = tokens[index];
         const contextValue = token.startsWith("--context=") ? token.slice("--context=".length) : undefined;
+        const judgeValue = token.startsWith("--judge=") ? token.slice("--judge=".length) : undefined;
         if (token === "--verbose" || token === "-v") {
             verbose = true;
         }
@@ -92,11 +94,22 @@ export function parseRun(input) {
             }
             contextMode = value;
         }
+        else if (judgeValue !== undefined) {
+            if (!judgeValue.trim())
+                throw new Error("--judge requires a non-empty backend name");
+            judge = judgeValue.trim();
+        }
+        else if (token === "--judge") {
+            const value = tokens[++index];
+            if (!value || !value.trim())
+                throw new Error("--judge requires a non-empty backend name");
+            judge = value.trim();
+        }
         else {
             args.push(token);
         }
     }
-    return { target, args, contextMode, verbose, debug };
+    return { target, args, contextMode, verbose, debug, judge };
 }
 export function parsePlan(input) {
     const tokens = splitArguments(input);
@@ -242,6 +255,17 @@ async function listDmlFiles(directory, prefix = "") {
 function modelLabel(ctx) {
     return ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "none selected";
 }
+function judgeBackendsEnabled(config) {
+    return config.judgment.jev.enabled ? ", jev" : "";
+}
+function jevStatus(config) {
+    const jev = config.judgment.jev;
+    if (!jev.enabled)
+        return "disabled";
+    return process.env[jev.apiKeyEnv]
+        ? `enabled (${jev.model})`
+        : `enabled but ${jev.apiKeyEnv} is not set`;
+}
 async function bundledViewerTemplate() {
     return readFile(fileURLToPath(new URL("./assets/viewer.template.html", import.meta.url)), "utf8");
 }
@@ -251,6 +275,18 @@ function viewerVendorAssetPath() {
 function publishResult(pi, content, details) {
     pi.sendMessage({ customType: "deepclause-result", content, display: true, details });
 }
+/**
+ * Ask the user a DeepClause question.
+ *
+ * Pi's interactive text-input dialog renders only its title: the placeholder
+ * argument is ignored by `ExtensionInputComponent`. Passing the question as the
+ * placeholder (as the extension used to) made it invisible, so put the whole
+ * question in the title and label which run is asking.
+ */
+export function requestDeepClauseInput(ctx, label, prompt, signal) {
+    const heading = label ? `DeepClause input — ${label}` : "DeepClause input";
+    return ctx.ui.input(`${heading}\n\n${prompt}`, undefined, { signal });
+}
 export default function deepClauseExtension(pi) {
     let activeController;
     let activeDescription;
@@ -260,6 +296,26 @@ export default function deepClauseExtension(pi) {
     let planCommitRegistered = false;
     let planningTransaction;
     let pendingAgentStep;
+    /**
+     * Claim the single DeepClause execution slot synchronously, before any await.
+     * Without this, parallel `dc_run` calls all pass the `activeController` check
+     * while the first one is still awaiting its setup, then run concurrently and
+     * fight over the one-slot pi input dialog (leaving earlier runs hung).
+     */
+    const claimExecution = (description) => {
+        if (activeController)
+            return undefined;
+        const controller = new AbortController();
+        activeController = controller;
+        activeDescription = description;
+        return controller;
+    };
+    const releaseExecution = (controller) => {
+        if (activeController === controller) {
+            activeController = undefined;
+            activeDescription = undefined;
+        }
+    };
     const setPlanCommitActive = (enabled) => {
         if (enabled && !planCommitRegistered) {
             pi.registerTool({
@@ -455,6 +511,7 @@ export default function deepClauseExtension(pi) {
                 promptGuidelines: [
                     "Use dc_run only for existing DML programs when their deterministic logic, constraints, or specialized orchestration is useful; do not use dc_run to compile natural language or create a skill.",
                     "Do not call dc_run while another DeepClause execution is active, and do not claim success unless dc_run returns an answer without errors.",
+                    "If dc_run reports execution_already_active, wait for the active run to finish and then retry this skill instead of reporting failure.",
                 ],
                 parameters: Type.Object({
                     skill: Type.String({ description: "Skill name such as example, or a DML path relative to .pi/deepclause/." }),
@@ -464,41 +521,40 @@ export default function deepClauseExtension(pi) {
                     })),
                 }),
                 async execute(_toolCallId, params, signal, onUpdate, ctx) {
-                    if (activeController) {
+                    const controller = claimExecution("dc_run");
+                    if (!controller) {
                         return {
-                            content: [{ type: "text", text: "DeepClause execution rejected: another execution is already active." }],
+                            content: [{ type: "text", text: "DeepClause execution rejected: another execution is active. Wait for it to finish, then call dc_run again for this skill." }],
                             details: { success: false, error: "execution_already_active" },
                         };
                     }
-                    const paths = await initializeWorkspace(ctx.cwd);
-                    const config = await loadConfig(paths.config);
-                    if (!config.modelToolEnabled || !pi.getActiveTools().includes(DC_RUN_TOOL)) {
-                        return {
-                            content: [{ type: "text", text: "The dc_run tool is disabled. The user can enable it with /dc-tool enable." }],
-                            details: { success: false, error: "tool_disabled" },
-                        };
-                    }
-                    const mode = params.context ?? config.contextMode;
-                    const filePath = await resolveDmlPath(paths, params.skill);
-                    if (await isContextualPlan(filePath)) {
-                        return {
-                            content: [{ type: "text", text: "Contextual DML plans must be started by the user with /dc-run; they cannot start a nested pi agent turn from dc_run." }],
-                            details: { success: false, error: "interactive_plan_requires_user_run" },
-                        };
-                    }
-                    const skillName = path.relative(paths.root, filePath);
-                    const initialMessages = buildInitialMessages(ctx.sessionManager.getBranch(), mode, config.branchMessageLimit);
-                    const controller = new AbortController();
                     const cancel = () => controller.abort(signal?.reason ?? new Error("dc_run cancelled"));
                     if (signal?.aborted)
                         cancel();
                     else
                         signal?.addEventListener("abort", cancel, { once: true });
-                    activeController = controller;
-                    activeDescription = `model tool running ${skillName}`;
-                    const startedAt = Date.now();
-                    const progress = [];
                     try {
+                        const paths = await initializeWorkspace(ctx.cwd);
+                        const config = await loadConfig(paths.config);
+                        if (!config.modelToolEnabled || !pi.getActiveTools().includes(DC_RUN_TOOL)) {
+                            return {
+                                content: [{ type: "text", text: "The dc_run tool is disabled. The user can enable it with /dc-tool enable." }],
+                                details: { success: false, error: "tool_disabled" },
+                            };
+                        }
+                        const mode = params.context ?? config.contextMode;
+                        const filePath = await resolveDmlPath(paths, params.skill);
+                        if (await isContextualPlan(filePath)) {
+                            return {
+                                content: [{ type: "text", text: "Contextual DML plans must be started by the user with /dc-run; they cannot start a nested pi agent turn from dc_run." }],
+                                details: { success: false, error: "interactive_plan_requires_user_run" },
+                            };
+                        }
+                        const skillName = path.relative(paths.root, filePath);
+                        activeDescription = `model tool running ${skillName}`;
+                        const initialMessages = buildInitialMessages(ctx.sessionManager.getBranch(), mode, config.branchMessageLimit);
+                        const startedAt = Date.now();
+                        const progress = [];
                         const result = await executeDml(filePath, params.args ?? [], initialMessages, config, pi, ctx, controller, {
                             onEvent: (event) => {
                                 if (event.type === "output" && event.content)
@@ -520,7 +576,7 @@ export default function deepClauseExtension(pi) {
                             onInput: async (prompt, inputSignal) => {
                                 if (!ctx.hasUI)
                                     throw new Error("dc_run cannot request user input without interactive UI");
-                                const answer = await ctx.ui.input("DeepClause input", prompt, { signal: inputSignal });
+                                const answer = await requestDeepClauseInput(ctx, skillName, prompt, inputSignal);
                                 if (answer === undefined)
                                     throw new Error("Input cancelled");
                                 return answer;
@@ -547,13 +603,12 @@ export default function deepClauseExtension(pi) {
                         const message = error instanceof Error ? error.message : String(error);
                         return {
                             content: [{ type: "text", text: `DeepClause execution failed: ${message}` }],
-                            details: { success: false, skill: skillName, contextMode: mode, error: message },
+                            details: { success: false, error: message },
                         };
                     }
                     finally {
                         signal?.removeEventListener("abort", cancel);
-                        activeController = undefined;
-                        activeDescription = undefined;
+                        releaseExecution(controller);
                     }
                 },
             });
@@ -572,11 +627,11 @@ export default function deepClauseExtension(pi) {
             pi.registerTool({
                 name: DC_DIAGRAM_TOOL,
                 label: "Create DeepClause Diagram",
-                description: "Create a presentation-grade or specification-grade Mermaid diagram from any .dml file, write a self-contained offline viewer under .pi/deepclause/diagrams/, and open it.",
+                description: "Create a presentation-grade or specification-grade Mermaid diagram from any .dml file, write a self-contained offline viewer under .pi/deepclause/diagrams/, and open it. The specification grade preserves the core decision logic and rule facts.",
                 promptSnippet: "Create a presentation- or specification-grade diagram from a DML file",
                 promptGuidelines: [
                     "Use dc_diagram whenever the user asks for a diagram, flowchart, or visual of a .dml file; pass the exact path the user named.",
-                    "Choose grade=presentation for slides and overviews and grade=specification for engineering detail; use grade=both only when the user asks for both.",
+                    "Choose grade=presentation for slides and overviews and grade=specification for engineering detail (decision predicates, thresholds, rule facts); use grade=both only when the user asks for both.",
                     "Do not hand-write Mermaid or run diagram tools yourself; call dc_diagram and report the viewer result.",
                 ],
                 parameters: Type.Object({
@@ -585,52 +640,47 @@ export default function deepClauseExtension(pi) {
                     view: Type.Optional(StringEnum(["flow", "sequence"], { description: "Base layout used to seed the grade; default flow." })),
                 }),
                 async execute(_toolCallId, params, signal, onUpdate, ctx) {
-                    if (activeController) {
+                    const controller = claimExecution("dc_diagram");
+                    if (!controller) {
                         return {
                             content: [{ type: "text", text: "Another DeepClause operation is already active; wait for it to finish." }],
                             details: { success: false, error: "execution_already_active" },
                         };
                     }
-                    const requested = resolveGrade(String(params.grade ?? "")) ?? "presentation";
-                    const grades = requested === "both" ? ["presentation", "specification"] : [requested];
-                    const view = params.view === "sequence" ? "sequence" : "flow";
-                    let sourcePath;
-                    try {
-                        sourcePath = await resolveDiagramSource(ctx.cwd, params.dml);
-                    }
-                    catch (error) {
-                        const message = error instanceof Error ? error.message : String(error);
-                        return { content: [{ type: "text", text: `dc_diagram failed: ${message}` }], details: { success: false, error: message } };
-                    }
-                    if (!ctx.model) {
-                        return {
-                            content: [{ type: "text", text: "dc_diagram requires an active pi model. Select one and try again." }],
-                            details: { success: false, error: "no_model" },
-                        };
-                    }
-                    const config = await loadConfig(getPaths(ctx.cwd).config);
-                    const source = await readFile(sourcePath, "utf8");
-                    const display = displayPath(ctx.cwd, sourcePath);
-                    const seed = view === "sequence"
-                        ? renderSequence(display, source)
-                        : renderDml(display, source, { hideOutput: true });
-                    const targets = await collectDiagramTargets(ctx.cwd, [sourcePath]);
-                    const name = diagramNameFor(sourcePath, targets, ctx.cwd);
-                    const { diagrams, vendor } = await ensureDiagramDir(ctx.cwd, viewerVendorAssetPath());
-                    const templateText = await bundledViewerTemplate();
-                    const controller = new AbortController();
                     const cancel = () => controller.abort(signal?.reason ?? new Error("dc_diagram cancelled"));
                     if (signal?.aborted)
                         cancel();
                     else
                         signal?.addEventListener("abort", cancel, { once: true });
-                    activeController = controller;
-                    activeDescription = `diagram ${name} (${grades.join("+")})`;
-                    const run = (command, args, options) => pi.exec(command, args, options);
-                    let chrome;
-                    let chromeResolved = false;
                     try {
+                        const requested = resolveGrade(String(params.grade ?? "")) ?? "presentation";
+                        const grades = requested === "both" ? ["presentation", "specification"] : [requested];
+                        const view = params.view === "sequence" ? "sequence" : "flow";
+                        const sourcePath = await resolveDiagramSource(ctx.cwd, params.dml);
+                        if (!ctx.model) {
+                            return {
+                                content: [{ type: "text", text: "dc_diagram requires an active pi model. Select one and try again." }],
+                                details: { success: false, error: "no_model" },
+                            };
+                        }
+                        const config = await loadConfig(getPaths(ctx.cwd).config);
+                        const source = await readFile(sourcePath, "utf8");
+                        const display = displayPath(ctx.cwd, sourcePath);
+                        const targets = await collectDiagramTargets(ctx.cwd, [sourcePath]);
+                        const name = diagramNameFor(sourcePath, targets, ctx.cwd);
+                        const { diagrams, vendor } = await ensureDiagramDir(ctx.cwd, viewerVendorAssetPath());
+                        const templateText = await bundledViewerTemplate();
+                        activeDescription = `diagram ${name} (${grades.join("+")})`;
+                        const run = (command, args, options) => pi.exec(command, args, options);
+                        let chrome;
+                        let chromeResolved = false;
                         for (const grade of grades) {
+                            // The specification seed carries the core decision logic and rule
+                            // facts; the presentation seed stays small so the model can keep
+                            // it to a general-audience overview.
+                            const seed = view === "sequence"
+                                ? renderSequence(display, source)
+                                : renderDml(display, source, { hideOutput: true, includeLogic: grade === "specification" });
                             const result = await polishDiagram({
                                 grade,
                                 view,
@@ -676,8 +726,7 @@ export default function deepClauseExtension(pi) {
                     }
                     finally {
                         signal?.removeEventListener("abort", cancel);
-                        activeController = undefined;
-                        activeDescription = undefined;
+                        releaseExecution(controller);
                     }
                 },
             });
@@ -727,7 +776,7 @@ export default function deepClauseExtension(pi) {
                         const viewer = displayPath(ctx.cwd, build.viewerPath);
                         return {
                             content: [{ type: "text", text: `Created spec graph (${view}). Viewer: ${viewer}${opened ? " (opened in your browser)" : ""}` }],
-                            details: { success: true, view, viewer, opened },
+                            details: { success: true, view, viewer, viewerPath: build.viewerPath, opened },
                         };
                     }
                     catch (error) {
@@ -744,13 +793,13 @@ export default function deepClauseExtension(pi) {
         }
     };
     const runSpecSkill = async (ctx, skill, args = [], options = {}) => {
-        const paths = await initializeWorkspace(ctx.cwd);
-        const config = await loadConfig(paths.config);
-        const filePath = await resolveDmlPath(paths, skill);
-        const controller = new AbortController();
-        activeController = controller;
-        activeDescription = `running ${skill}`;
+        const controller = claimExecution(`running ${skill}`);
+        if (!controller)
+            throw new Error("Another DeepClause execution is already active");
         try {
+            const paths = await initializeWorkspace(ctx.cwd);
+            const config = await loadConfig(paths.config);
+            const filePath = await resolveDmlPath(paths, skill);
             const result = await executeDml(filePath, args, [], config, pi, ctx, controller, {
                 onEvent() { },
                 onInput: async () => { throw new Error("spec skills do not request input"); },
@@ -760,8 +809,7 @@ export default function deepClauseExtension(pi) {
             return result.answer ?? "(no answer)";
         }
         finally {
-            activeController = undefined;
-            activeDescription = undefined;
+            releaseExecution(controller);
         }
     };
     pi.on("session_start", async (_event, ctx) => {
@@ -844,6 +892,8 @@ export default function deepClauseExtension(pi) {
                 `Skills: ${path.relative(ctx.cwd, paths.skills)}`,
                 `Plans: ${path.relative(ctx.cwd, paths.plans)}`,
                 `Context: ${config.contextMode} (verbose default: ${config.verbose})`,
+                `Judgment: ${config.judgment.default} (backends: llm${judgeBackendsEnabled(config)})`,
+                `Jev: ${jevStatus(config)}`,
                 `Model tool (${DC_RUN_TOOL}): ${config.modelToolEnabled && pi.getActiveTools().includes(DC_RUN_TOOL) ? "enabled" : "disabled"}`,
                 `Model tool (${DC_DIAGRAM_TOOL}): ${pi.getActiveTools().includes(DC_DIAGRAM_TOOL) ? "enabled" : "disabled"}`,
                 "Ask pi for a presentation-grade or specification-grade diagram of any .dml file;",
@@ -854,10 +904,13 @@ export default function deepClauseExtension(pi) {
                 "  /dc-check <change|spec>            validate specs and deltas deterministically",
                 "  /dc-archive <change>              merge a change delta into specs/ and archive it",
                 "  /dc-apply <change> [--abort]       execute tasks.dml; --abort discards an interrupted apply",
-                "  /dc-run <skill|path> [args] [--context=turn|branch|isolated]",
+                "  /dc-run <skill|path> [args] [--context=turn|branch|isolated] [--judge=llm|jev]",
                 "  /dc-run <skill|path> --verbose   show lifecycle events",
                 "  /dc-run <skill|path> --debug     show full event payloads and SDK diagnostics",
                 "  /dc-tool enable|disable|status   control the model-callable dc_run tool",
+                "  /dc-judge [enable|disable|status]  select the judgment backend (llm|jev)",
+                "  /dc-judge default llm|jev        set the default judgment backend",
+                "  /dc-judge model <name> | key-env <ENV_VAR>",
                 "  /dc-cancel",
             ].join("\n");
             ctx.ui.notify(message, "info");
@@ -949,6 +1002,73 @@ export default function deepClauseExtension(pi) {
             }
         },
     });
+    pi.registerCommand("dc-judge", {
+        description: "Enable, disable, or select the semantic judgment backend (llm|jev)",
+        handler: async (rawArgs, ctx) => {
+            const tokens = rawArgs.trim().split(/\s+/).filter(Boolean);
+            const action = (tokens[0] ?? "status").toLowerCase();
+            const paths = await initializeWorkspace(ctx.cwd);
+            const describe = (config) => {
+                const jev = config.judgment.jev;
+                const keyPresent = Boolean(process.env[jev.apiKeyEnv]);
+                return [
+                    `judgment backend: ${config.judgment.default}`,
+                    `registered backends: llm${jev.enabled ? ", jev" : ""}`,
+                    `jev: ${jev.enabled ? "enabled" : "disabled"} | model=${jev.model} | ${jev.apiKeyEnv}=${keyPresent ? "set" : "not set"}`,
+                ].join("\n");
+            };
+            try {
+                if (action === "status") {
+                    ctx.ui.notify(describe(await loadConfig(paths.config)), "info");
+                    return;
+                }
+                if (action === "enable" || action === "on" || action === "disable" || action === "off") {
+                    const enabled = action === "enable" || action === "on";
+                    const config = await setJudgeConfig(paths.config, { jev: { enabled } });
+                    const jev = config.judgment.jev;
+                    const note = enabled && !process.env[jev.apiKeyEnv]
+                        ? `\n${jev.apiKeyEnv} is not set; export it before using --judge=jev.`
+                        : "";
+                    ctx.ui.notify(`Jev backend ${enabled ? "enabled" : "disabled"} for this workspace.${note}`, enabled ? "warning" : "info");
+                    return;
+                }
+                if (action === "default") {
+                    const name = tokens[1];
+                    if (name !== "llm" && name !== "jev") {
+                        ctx.ui.notify("Usage: /dc-judge default llm|jev", "warning");
+                        return;
+                    }
+                    await setJudgeConfig(paths.config, { default: name });
+                    ctx.ui.notify(`Default judgment backend set to '${name}'`, "info");
+                    return;
+                }
+                if (action === "model") {
+                    const model = tokens[1];
+                    if (!model) {
+                        ctx.ui.notify("Usage: /dc-judge model <name>", "warning");
+                        return;
+                    }
+                    await setJudgeConfig(paths.config, { jev: { model } });
+                    ctx.ui.notify(`Jev model set to '${model}'`, "info");
+                    return;
+                }
+                if (action === "key-env") {
+                    const envName = tokens[1];
+                    if (!envName) {
+                        ctx.ui.notify("Usage: /dc-judge key-env <ENV_VAR>", "warning");
+                        return;
+                    }
+                    await setJudgeConfig(paths.config, { jev: { apiKeyEnv: envName } });
+                    ctx.ui.notify(`Jev API key environment variable set to '${envName}'`, "info");
+                    return;
+                }
+                ctx.ui.notify("Usage: /dc-judge [enable|disable|status|default llm|jev|model <name>|key-env <ENV_VAR>]", "warning");
+            }
+            catch (error) {
+                ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+            }
+        },
+    });
     pi.registerCommand("dc-list", {
         description: "List DeepClause DML skills and generated plans",
         handler: async (_args, ctx) => {
@@ -1098,7 +1218,8 @@ export default function deepClauseExtension(pi) {
     pi.registerCommand("dc-run", {
         description: "Run a DML skill with pi's active model",
         handler: async (rawArgs, ctx) => {
-            if (activeController) {
+            const controller = claimExecution("dc-run");
+            if (!controller) {
                 ctx.ui.notify("A DeepClause execution is already active", "warning");
                 return;
             }
@@ -1133,8 +1254,6 @@ export default function deepClauseExtension(pi) {
                 }
                 const mode = parsed.contextMode ?? config.contextMode;
                 const initialMessages = buildInitialMessages(ctx.sessionManager.getBranch(), mode, config.branchMessageLimit);
-                const controller = new AbortController();
-                activeController = controller;
                 const outputLines = [];
                 const recentEvents = [];
                 const events = [];
@@ -1209,11 +1328,11 @@ export default function deepClauseExtension(pi) {
                     renderExecution();
                 };
                 try {
-                    const result = await executeDml(filePath, parsed.args, initialMessages, { ...config, verbose: config.verbose || parsed.debug }, pi, ctx, controller, {
+                    const result = await executeDml(filePath, parsed.args, initialMessages, { ...config, verbose: config.verbose || parsed.debug, judgeBackend: parsed.judge }, pi, ctx, controller, {
                         onEvent,
                         onDiagnostic,
                         onInput: async (prompt, signal) => {
-                            const answer = await ctx.ui.input("DeepClause input", prompt, { signal });
+                            const answer = await requestDeepClauseInput(ctx, skillName, prompt, signal);
                             if (answer === undefined)
                                 throw new Error("Input cancelled");
                             return answer;
@@ -1244,8 +1363,7 @@ export default function deepClauseExtension(pi) {
                 ctx.ui.notify(message, activeController?.signal.aborted ? "warning" : "error");
             }
             finally {
-                activeController = undefined;
-                activeDescription = undefined;
+                releaseExecution(controller);
                 ctx.ui.setStatus(STATUS_KEY, undefined);
                 ctx.ui.setWidget(WIDGET_KEY, undefined);
             }

package/dist/runtime.d.ts

@@ -41,4 +41,6 @@ export interface ExecutionResult {
     errors: string[];
     usage: LLMUsage;
 }
-export declare function executeDml(filePath: string, args: string[], initialMessages: MemoryMessage[], config: DeepClauseConfig, pi: ExtensionAPI, ctx: ExtensionContext, controller: AbortController, callbacks: ExecutionCallbacks, runPiAgentStep?: (request: PiAgentStepRequest, signal: AbortSignal) => Promise<PiAgentStepResult>, verifyCommands?: string[], applyChangeJsonPath?: string): Promise<ExecutionResult>;
+export declare function executeDml(filePath: string, args: string[], initialMessages: MemoryMessage[], config: DeepClauseConfig & {
+    judgeBackend?: string;
+}, pi: ExtensionAPI, ctx: ExtensionContext, controller: AbortController, callbacks: ExecutionCallbacks, runPiAgentStep?: (request: PiAgentStepRequest, signal: AbortSignal) => Promise<PiAgentStepResult>, verifyCommands?: string[], applyChangeJsonPath?: string): Promise<ExecutionResult>;

package/dist/runtime.js

@@ -1,6 +1,6 @@
 import { realpath, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { createDeepClause } from "deepclause-sdk";
+import { createDeepClause, createJevJudgeBackend, createLLMJudgeBackend } from "deepclause-sdk";
 import { PI_AGENT_STEP_TOOL } from "./planner.js";
 export const PI_WORKSPACE_LIST_TOOL = "pi_workspace_list";
 export const PI_BASH_TOOL = "pi_bash";
@@ -265,12 +265,33 @@ export async function executeDml(filePath, args, initialMessages, config, pi, ct
     if (!model)
         throw new Error("Select a pi model before running DeepClause");
     const backend = createPiBackend(ctx, config.maxTokens, callbacks.onDiagnostic ?? (() => { }));
+    // Judgment backends. `llm` reuses pi's active model and credentials; `jev`
+    // is opt-in and only registered when enabled and its key is present.
+    const judgeBackends = {
+        llm: createLLMJudgeBackend({ llmBackend: backend, model: model.id }),
+    };
+    const jev = config.judgment.jev;
+    if (jev.enabled) {
+        const apiKey = process.env[jev.apiKeyEnv];
+        if (apiKey) {
+            judgeBackends.jev = createJevJudgeBackend({ apiKey, model: jev.model });
+        }
+        else {
+            callbacks.onDiagnostic?.(`judgment backend 'jev' is enabled but ${jev.apiKeyEnv} is not set; falling back to 'llm'`);
+        }
+    }
+    const requestedJudge = config.judgeBackend ?? config.judgment.default;
+    if (!judgeBackends[requestedJudge]) {
+        throw new Error(`Judgment backend '${requestedJudge}' is not available. Enable it in .pi/deepclause/config.json or use --judge=llm.`);
+    }
     const sdk = await createDeepClause({
         model: model.id,
         maxTokens: config.maxTokens,
         streaming: true,
         debug: config.verbose,
         llmBackend: backend,
+        judgeBackends,
+        defaultJudge: requestedJudge,
     });
     registerPiRuntimeTools(sdk, pi, ctx.cwd, controller.signal, async (command, signal) => {
         if (!ctx.hasUI)
@@ -371,6 +392,7 @@ export async function executeDml(filePath, args, initialMessages, config, pi, ct
             gasLimit: config.gasLimit,
             signal: controller.signal,
             initialMessages,
+            judgeBackend: config.judgeBackend,
             onUserInput: (prompt) => callbacks.onInput(prompt, controller.signal),
         })) {
             callbacks.onEvent(event);

package/docs/SPECKIT.md

@@ -16,6 +16,16 @@ Spec-driven changes for pi, without leaving the session.
 /dc-archive <slug>                   merge into specs/
 ```
 
+## Why DML and DeepClause for spec-driven development
+
+Most spec tools are a Markdown convention plus a program that parses it. The convention is the good idea; the program is where it gets fragile, because parsing, validating and merging structured text is usually written as regexes and imperative branches. OpenSpec, for example, needs a few thousand lines of TypeScript for what is essentially parsing requirements, checking coverage, and reconciling deltas — and its own docs warn about silent failures such as a scenario written with three hashes instead of four.
+
+Spec work is logic. A requirement is a term; *every requirement has at least one scenario* is a rule; merging a delta is matching and rewriting; *which scenarios are uncovered?* and *do two in-flight changes touch the same requirement?* are queries. DML is a Prolog dialect, so these are expressed directly instead of emulated. Structure is parsed once into terms, so validation is a decision procedure with line numbers, merging preserves untouched blocks, and coverage and conflict checks are single queries — deterministic, zero tokens, reproducible in CI.
+
+That determinism is the point. The value of agreeing on a spec is that the agreement is *checkable*; if the check is another model call, it is just another opinion. DML lets the model do what it is good at — drafting requirements, designing, implementing — and keeps correctness in logic. The same runtime supplies what raw Prolog lacks: `task/N` and `prompt/N` for bounded model calls with typed results, `exec/2` for tools, streaming events, cancellation, and usage accounting. Backtracking across model calls is what makes verify → repair → retry loops natural, and CLP(FD)/(Q)/(R) cover hard constraints instead of asking the model to do arithmetic.
+
+DeepClause is what makes that practical inside pi: DML programs run with pi's active model, credentials, session context and approvals, so the spec engine, the task plan (`tasks.dml`), and the execution loop are one system in the session you already work in, rather than a separate CLI. You keep human-readable Markdown specs, but the thing enforcing them is a proof, not a prompt.
+
 ## Requirements
 
 - pi with this extension installed (see the [README](../README.md#install)).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepclause-pi",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Pi-hosted runtime for DeepClause DML programs",
   "type": "module",
   "license": "MIT",
@@ -43,7 +43,7 @@
     "prepublishOnly": "npm run check"
   },
   "dependencies": {
-    "deepclause-sdk": "npm:deepclause-sdk@0.0.87",
+    "deepclause-sdk": "npm:deepclause-sdk@0.0.89",
     "typebox": "1.3.7"
   },
   "peerDependencies": {