deepclause-pi 0.3.0 → 0.4.0

package/dist/config.d.ts

@@ -1,4 +1,17 @@
 export type ContextMode = "turn" | "branch" | "isolated";
+export interface JevJudgeConfig {
+    /** Whether the Jev (TypeSafe System One) backend may be used. */
+    enabled: boolean;
+    /** Model alias or pinned version passed to TypeSafe. */
+    model: string;
+    /** Environment variable holding the TypeSafe API key. */
+    apiKeyEnv: string;
+}
+export interface JudgmentConfig {
+    /** Default backend name: "llm", "jev", or a name registered by an extension. */
+    default: string;
+    jev: JevJudgeConfig;
+}
 export interface DeepClauseConfig {
     version: 1;
     contextMode: ContextMode;
@@ -7,7 +20,16 @@ export interface DeepClauseConfig {
     maxTokens: number;
     verbose: boolean;
     modelToolEnabled: boolean;
+    judgment: JudgmentConfig;
 }
 export declare const DEFAULT_CONFIG: DeepClauseConfig;
 export declare function loadConfig(path: string): Promise<DeepClauseConfig>;
 export declare function setModelToolEnabled(configPath: string, enabled: boolean): Promise<DeepClauseConfig>;
+export interface JudgeConfigPatch {
+    /** Default backend name ("llm" or "jev"). */
+    default?: string;
+    /** Partial update of the Jev backend settings. */
+    jev?: Partial<JevJudgeConfig>;
+}
+/** Merge a judgment patch into the workspace config, preserving every other field. */
+export declare function setJudgeConfig(configPath: string, patch: JudgeConfigPatch): Promise<DeepClauseConfig>;

package/dist/config.js

@@ -7,6 +7,10 @@ export const DEFAULT_CONFIG = {
     maxTokens: 16_384,
     verbose: false,
     modelToolEnabled: false,
+    judgment: {
+        default: "llm",
+        jev: { enabled: false, model: "jev-latest", apiKeyEnv: "TYPESAFE_API_KEY" },
+    },
 };
 const isContextMode = (value) => value === "turn" || value === "branch" || value === "isolated";
 export async function loadConfig(path) {
@@ -40,6 +44,40 @@ export async function loadConfig(path) {
         maxTokens: positiveInteger("maxTokens", DEFAULT_CONFIG.maxTokens),
         verbose: config.verbose === true,
         modelToolEnabled: config.modelToolEnabled === true,
+        judgment: parseJudgmentConfig(config.judgment),
+    };
+}
+function parseJudgmentConfig(value) {
+    if (value === undefined)
+        return DEFAULT_CONFIG.judgment;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("judgment must be a JSON object");
+    }
+    const judgment = value;
+    const defaultBackend = judgment.default ?? DEFAULT_CONFIG.judgment.default;
+    if (typeof defaultBackend !== "string" || !defaultBackend.trim()) {
+        throw new Error("judgment.default must be a non-empty backend name");
+    }
+    const jevValue = judgment.jev ?? {};
+    if (!jevValue || typeof jevValue !== "object" || Array.isArray(jevValue)) {
+        throw new Error("judgment.jev must be a JSON object");
+    }
+    const jev = jevValue;
+    const model = jev.model ?? DEFAULT_CONFIG.judgment.jev.model;
+    const apiKeyEnv = jev.apiKeyEnv ?? DEFAULT_CONFIG.judgment.jev.apiKeyEnv;
+    if (typeof model !== "string" || !model.trim()) {
+        throw new Error("judgment.jev.model must be a non-empty string");
+    }
+    if (typeof apiKeyEnv !== "string" || !apiKeyEnv.trim()) {
+        throw new Error("judgment.jev.apiKeyEnv must be a non-empty environment variable name");
+    }
+    return {
+        default: defaultBackend.trim(),
+        jev: {
+            enabled: jev.enabled === true,
+            model: model.trim(),
+            apiKeyEnv: apiKeyEnv.trim(),
+        },
     };
 }
 export async function setModelToolEnabled(configPath, enabled) {
@@ -57,3 +95,25 @@ export async function setModelToolEnabled(configPath, enabled) {
     await writeFile(configPath, `${JSON.stringify({ ...existing, modelToolEnabled: enabled }, null, 2)}\n`, "utf8");
     return loadConfig(configPath);
 }
+/** Merge a judgment patch into the workspace config, preserving every other field. */
+export async function setJudgeConfig(configPath, patch) {
+    let existing = {};
+    try {
+        const parsed = JSON.parse(await readFile(configPath, "utf8"));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+            existing = parsed;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw new Error(`Invalid DeepClause config: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const record = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+    const nextJudgment = {
+        ...record(existing.judgment),
+        ...(patch.default !== undefined ? { default: patch.default } : {}),
+        jev: { ...record(record(existing.judgment).jev), ...(patch.jev ?? {}) },
+    };
+    await writeFile(configPath, `${JSON.stringify({ ...existing, judgment: nextJudgment }, null, 2)}\n`, "utf8");
+    return loadConfig(configPath);
+}

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export interface ParsedRun {
     contextMode?: ContextMode;
     verbose: boolean;
     debug: boolean;
+    judge?: string;
 }
 interface ParsedPlan {
     request: string;

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");
 }
@@ -727,7 +751,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) {
@@ -844,6 +868,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 +880,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 +978,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) => {
@@ -1209,7 +1305,7 @@ 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) => {

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.4.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": {

package/src/assets/apply.dml

@@ -85,7 +85,7 @@ attempt(TasksPath, Statuses0, Change, Id, Props, N, Max, Feedback, Statuses) :-
     format(string(Progress), "task ~w attempt ~w/~w", [Id, N, Max]),
     output(Progress),
     execute(Change, Id, Props, Feedback, Summary),
-    verify(Props, Summary, Verdict),
+    verify_task(Props, Summary, Verdict),
     (   Verdict = ok
     ->  sp_set_status(Statuses0, Id, done(N), Statuses),
         sp_write_statuses(TasksPath, Statuses),
@@ -123,7 +123,7 @@ build_instruction(Id, Do, Expected, Feedback, Instruction) :-
         "Task ~w. ~w~nExpected result: ~w~n~nThe previous attempt failed verification: ~w~nFix only what is needed; do not redo the whole task.",
         [Id, Do, Expected, Feedback]).
 
-verify(Props, Summary, Verdict) :-
+verify_task(Props, Summary, Verdict) :-
     catch(get_dict(checks, Props, Checks), _, Checks = []),
     findall(Message, (member(Check, Checks), run_check(Check, Message), Message \= ok), Failures),
     (   Summary == ""

package/src/assets/specs.dml

@@ -64,9 +64,12 @@ sp_sections(Lines, Sections) :-
     sp_skip_plain(Lines, Rest),
     sp_sections_from(Rest, Sections).
 
-sp_skip_plain([line(Line, Number)|Rest], [line(Line, Number)|Rest]) :- sp_heading(Line, Level, _), Level >= 1, Level =< 3, !.
-sp_skip_plain([_|Rest], Out) :- sp_skip_plain(Rest, Out).
 sp_skip_plain([], []).
+sp_skip_plain([Item|Rest], Out) :-
+    (   Item = line(Line, _), sp_heading(Line, Level, _), Level >= 1, Level =< 3
+    ->  Out = [Item|Rest]
+    ;   sp_skip_plain(Rest, Out)
+    ).
 
 sp_sections_from([], []).
 sp_sections_from([line(Line, N)|Rest], [section(Level, Text, N, Body)|More]) :-
@@ -77,12 +80,11 @@ sp_sections_from([line(Line, N)|Rest], [section(Level, Text, N, Body)|More]) :-
     sp_sections_from(Tail, More).
 
 sp_take_body([], [], []).
-sp_take_body([line(Line, Number)|Rest], [], [line(Line, Number)|Rest]) :-
-    sp_heading(Line, Level, _),
-    Level >= 1,
-    Level =< 3,
-    !.
-sp_take_body([Item|Rest], [Item|Body], Tail) :- sp_take_body(Rest, Body, Tail).
+sp_take_body([Item|Rest], Body, Tail) :-
+    (   Item = line(Line, _), sp_heading(Line, Level, _), Level >= 1, Level =< 3
+    ->  Body = [], Tail = [Item|Rest]
+    ;   Body = [Item|Body1], sp_take_body(Rest, Body1, Tail)
+    ).
 
 %% Split a requirement body (level-4 headings inline) into description + scenarios.
 sp_split_scenarios(Body, DescLines, ScenarioSections) :-
@@ -90,11 +92,11 @@ sp_split_scenarios(Body, DescLines, ScenarioSections) :-
     sp_scenario_sections(Rest, ScenarioSections).
 
 sp_take_plain([], [], []).
-sp_take_plain([line(Line, Number)|Rest], [], [line(Line, Number)|Rest]) :-
-    sp_heading(Line, Level, _),
-    Level >= 4,
-    !.
-sp_take_plain([Item|Rest], [Item|Body], Tail) :- sp_take_plain(Rest, Body, Tail).
+sp_take_plain([Item|Rest], Body, Tail) :-
+    (   Item = line(Line, _), sp_heading(Line, Level, _), Level >= 4
+    ->  Body = [], Tail = [Item|Rest]
+    ;   Body = [Item|Body1], sp_take_plain(Rest, Body1, Tail)
+    ).
 
 sp_scenario_sections([], []).
 sp_scenario_sections([line(Line, N)|Rest], [section(4, Text, N, Body)|More]) :-
@@ -103,11 +105,11 @@ sp_scenario_sections([line(Line, N)|Rest], [section(4, Text, N, Body)|More]) :-
     sp_scenario_sections(Tail, More).
 
 sp_take_until_level4([], [], []).
-sp_take_until_level4([line(Line, Number)|Rest], [], [line(Line, Number)|Rest]) :-
-    sp_heading(Line, Level, _),
-    Level >= 4,
-    !.
-sp_take_until_level4([Item|Rest], [Item|Body], Tail) :- sp_take_until_level4(Rest, Body, Tail).
+sp_take_until_level4([Item|Rest], Body, Tail) :-
+    (   Item = line(Line, _), sp_heading(Line, Level, _), Level >= 4
+    ->  Body = [], Tail = [Item|Rest]
+    ;   Body = [Item|Body1], sp_take_until_level4(Rest, Body1, Tail)
+    ).
 
 %% ---------------------------------------------------------------------------
 %% Term extraction
@@ -164,10 +166,11 @@ sp_parse_delta(Text, Deltas) :-
     sp_collect_ops(Rest, Deltas).
 
 sp_drop_to_op([], []).
-sp_drop_to_op([section(2, Header, Number, Body)|Rest], [section(2, Header, Number, Body)|Rest]) :-
-    sp_delta_header(Header, _),
-    !.
-sp_drop_to_op([_|Rest], Out) :- sp_drop_to_op(Rest, Out).
+sp_drop_to_op([Item|Rest], Out) :-
+    (   Item = section(2, Header, _, _), sp_delta_header(Header, _)
+    ->  Out = [Item|Rest]
+    ;   sp_drop_to_op(Rest, Out)
+    ).
 
 sp_collect_ops([], []).
 sp_collect_ops([section(2, Header, _, _)|Rest], Deltas) :-
@@ -184,10 +187,11 @@ sp_collect_ops([section(2, Header, _, _)|Rest], Deltas) :-
     ).
 
 sp_take_until_op([], [], []).
-sp_take_until_op([section(2, Header, Number, Body)|Rest], [], [section(2, Header, Number, Body)|Rest]) :-
-    sp_delta_header(Header, _),
-    !.
-sp_take_until_op([Item|Rest], [Item|Group], Tail) :- sp_take_until_op(Rest, Group, Tail).
+sp_take_until_op([Item|Rest], Group, Tail) :-
+    (   Item = section(2, Header, _, _), sp_delta_header(Header, _)
+    ->  Group = [], Tail = [Item|Rest]
+    ;   Group = [Item|Group1], sp_take_until_op(Rest, Group1, Tail)
+    ).
 
 %% ---------------------------------------------------------------------------
 %% Validation

package/src/config.ts

@@ -2,6 +2,21 @@ import { readFile, writeFile } from "node:fs/promises";
 
 export type ContextMode = "turn" | "branch" | "isolated";
 
+export interface JevJudgeConfig {
+  /** Whether the Jev (TypeSafe System One) backend may be used. */
+  enabled: boolean;
+  /** Model alias or pinned version passed to TypeSafe. */
+  model: string;
+  /** Environment variable holding the TypeSafe API key. */
+  apiKeyEnv: string;
+}
+
+export interface JudgmentConfig {
+  /** Default backend name: "llm", "jev", or a name registered by an extension. */
+  default: string;
+  jev: JevJudgeConfig;
+}
+
 export interface DeepClauseConfig {
   version: 1;
   contextMode: ContextMode;
@@ -10,6 +25,7 @@ export interface DeepClauseConfig {
   maxTokens: number;
   verbose: boolean;
   modelToolEnabled: boolean;
+  judgment: JudgmentConfig;
 }
 
 export const DEFAULT_CONFIG: DeepClauseConfig = {
@@ -20,6 +36,10 @@ export const DEFAULT_CONFIG: DeepClauseConfig = {
   maxTokens: 16_384,
   verbose: false,
   modelToolEnabled: false,
+  judgment: {
+    default: "llm",
+    jev: { enabled: false, model: "jev-latest", apiKeyEnv: "TYPESAFE_API_KEY" },
+  },
 };
 
 const isContextMode = (value: unknown): value is ContextMode =>
@@ -55,6 +75,42 @@ export async function loadConfig(path: string): Promise<DeepClauseConfig> {
     maxTokens: positiveInteger("maxTokens", DEFAULT_CONFIG.maxTokens),
     verbose: config.verbose === true,
     modelToolEnabled: config.modelToolEnabled === true,
+    judgment: parseJudgmentConfig(config.judgment),
+  };
+}
+
+function parseJudgmentConfig(value: unknown): JudgmentConfig {
+  if (value === undefined) return DEFAULT_CONFIG.judgment;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("judgment must be a JSON object");
+  }
+  const judgment = value as Record<string, unknown>;
+  const defaultBackend = judgment.default ?? DEFAULT_CONFIG.judgment.default;
+  if (typeof defaultBackend !== "string" || !defaultBackend.trim()) {
+    throw new Error("judgment.default must be a non-empty backend name");
+  }
+
+  const jevValue = judgment.jev ?? {};
+  if (!jevValue || typeof jevValue !== "object" || Array.isArray(jevValue)) {
+    throw new Error("judgment.jev must be a JSON object");
+  }
+  const jev = jevValue as Record<string, unknown>;
+  const model = jev.model ?? DEFAULT_CONFIG.judgment.jev.model;
+  const apiKeyEnv = jev.apiKeyEnv ?? DEFAULT_CONFIG.judgment.jev.apiKeyEnv;
+  if (typeof model !== "string" || !model.trim()) {
+    throw new Error("judgment.jev.model must be a non-empty string");
+  }
+  if (typeof apiKeyEnv !== "string" || !apiKeyEnv.trim()) {
+    throw new Error("judgment.jev.apiKeyEnv must be a non-empty environment variable name");
+  }
+
+  return {
+    default: defaultBackend.trim(),
+    jev: {
+      enabled: jev.enabled === true,
+      model: model.trim(),
+      apiKeyEnv: apiKeyEnv.trim(),
+    },
   };
 }
 
@@ -72,3 +128,38 @@ export async function setModelToolEnabled(configPath: string, enabled: boolean):
   await writeFile(configPath, `${JSON.stringify({ ...existing, modelToolEnabled: enabled }, null, 2)}\n`, "utf8");
   return loadConfig(configPath);
 }
+
+export interface JudgeConfigPatch {
+  /** Default backend name ("llm" or "jev"). */
+  default?: string;
+  /** Partial update of the Jev backend settings. */
+  jev?: Partial<JevJudgeConfig>;
+}
+
+/** Merge a judgment patch into the workspace config, preserving every other field. */
+export async function setJudgeConfig(
+  configPath: string,
+  patch: JudgeConfigPatch,
+): Promise<DeepClauseConfig> {
+  let existing: Record<string, unknown> = {};
+  try {
+    const parsed: unknown = JSON.parse(await readFile(configPath, "utf8"));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) existing = parsed as Record<string, unknown>;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw new Error(`Invalid DeepClause config: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  const record = (value: unknown): Record<string, unknown> =>
+    value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+
+  const nextJudgment = {
+    ...record(existing.judgment),
+    ...(patch.default !== undefined ? { default: patch.default } : {}),
+    jev: { ...record(record(existing.judgment).jev), ...(patch.jev ?? {}) },
+  };
+
+  await writeFile(configPath, `${JSON.stringify({ ...existing, judgment: nextJudgment }, null, 2)}\n`, "utf8");
+  return loadConfig(configPath);
+}

package/src/index.ts

@@ -6,7 +6,7 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import type { DMLEvent } from "deepclause-sdk";
 import { Type } from "typebox";
 import { buildInitialMessages } from "./context.js";
-import { loadConfig, setModelToolEnabled, type ContextMode } from "./config.js";
+import { loadConfig, setJudgeConfig, setModelToolEnabled, type ContextMode, type DeepClauseConfig } from "./config.js";
 import { renderDml, renderSequence } from "./diagram/extract.js";
 import { polishDiagram, resolveGrade, type DiagramGrade } from "./diagram/grade.js";
 import { findChrome, validateMermaid, type MermaidView } from "./diagram/validate.js";
@@ -57,6 +57,7 @@ export interface ParsedRun {
   contextMode?: ContextMode;
   verbose: boolean;
   debug: boolean;
+  judge?: string;
 }
 
 interface ParsedPlan {
@@ -125,11 +126,13 @@ export function parseRun(input: string): ParsedRun {
   let contextMode: ContextMode | undefined;
   let verbose = false;
   let debug = false;
+  let judge: string | undefined;
   const args: string[] = [];
 
   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;
     } else if (token === "--debug" || token === "-d") {
@@ -146,11 +149,18 @@ export function parseRun(input: string): ParsedRun {
         throw new Error("--context must be turn, branch, or isolated");
       }
       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: string): ParsedPlan {
@@ -288,6 +298,18 @@ function modelLabel(ctx: ExtensionCommandContext): string {
   return ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "none selected";
 }
 
+function judgeBackendsEnabled(config: DeepClauseConfig): string {
+  return config.judgment.jev.enabled ? ", jev" : "";
+}
+
+function jevStatus(config: DeepClauseConfig): string {
+  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(): Promise<string> {
   return readFile(fileURLToPath(new URL("./assets/viewer.template.html", import.meta.url)), "utf8");
 }
@@ -789,7 +811,7 @@ export default function deepClauseExtension(pi: ExtensionAPI) {
             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) {
             const message = error instanceof Error ? error.message : String(error);
@@ -926,6 +948,8 @@ export default function deepClauseExtension(pi: ExtensionAPI) {
         `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;",
@@ -936,10 +960,13 @@ export default function deepClauseExtension(pi: ExtensionAPI) {
         "  /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");
@@ -1032,6 +1059,78 @@ export default function deepClauseExtension(pi: ExtensionAPI) {
     },
   });
 
+  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: DeepClauseConfig): string => {
+        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) => {
@@ -1302,7 +1401,7 @@ export default function deepClauseExtension(pi: ExtensionAPI) {
             filePath,
             parsed.args,
             initialMessages,
-            { ...config, verbose: config.verbose || parsed.debug },
+            { ...config, verbose: config.verbose || parsed.debug, judgeBackend: parsed.judge },
             pi,
             ctx,
             controller,

package/src/runtime.ts

@@ -1,8 +1,9 @@
 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 type {
   DMLEvent,
+  JudgeBackend,
   LLMBackend,
   LLMBackendMessage,
   LLMUsage,
@@ -327,7 +328,7 @@ export async function executeDml(
   filePath: string,
   args: string[],
   initialMessages: MemoryMessage[],
-  config: DeepClauseConfig,
+  config: DeepClauseConfig & { judgeBackend?: string },
   pi: ExtensionAPI,
   ctx: ExtensionContext,
   controller: AbortController,
@@ -339,12 +340,38 @@ export async function executeDml(
   const model = ctx.model;
   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: Record<string, JudgeBackend> = {
+    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,
@@ -458,6 +485,7 @@ export async function executeDml(
       gasLimit: config.gasLimit,
       signal: controller.signal,
       initialMessages,
+      judgeBackend: config.judgeBackend,
       onUserInput: (prompt) => callbacks.onInput(prompt, controller.signal),
     })) {
       callbacks.onEvent(event);