deepclause-pi 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,22 +1,23 @@
-import { readFile, readdir } from "node:fs/promises";
+import { access, mkdir, readFile, readdir, rename } from "node:fs/promises";
 import path from "node:path";
 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";
-import { buildViewer, openViewerInBrowser, writeSidecar, } from "./diagram/viewer.js";
+import { buildEntriesViewer, buildViewer, openViewerInBrowser, writeSidecar, } from "./diagram/viewer.js";
 import { collectDiagramTargets, diagramNameFor, displayPath, ensureDiagramDir, resolveDiagramSource, } from "./diagram/workspace.js";
 import { completeTextWithPiModel } from "./model.js";
-import { executeDml } from "./runtime.js";
+import { executeDml, gitRestore } from "./runtime.js";
 import { getPaths, initializeWorkspace, resolveDmlPath } from "./workspace.js";
-import { assemblePlanDml, buildPlanningPrompt, DC_PLAN_COMMIT_TOOL, isContextualPlan, PI_AGENT_STEP_TOOL, readPlanRequiredTools, validateGeneratedPlan, validatePlanSpec, writePlanNonDestructively, } from "./planner.js";
+import { assemblePlanDml, assembleTasksDml, buildPlanningPrompt, DC_PLAN_COMMIT_TOOL, isContextualPlan, normalizePlanSlug, PI_AGENT_STEP_TOOL, readPlanRequiredTools, validateGeneratedPlan, validateGeneratedTasks, validatePlanSpec, writeChangeTasks, writePlanNonDestructively, } from "./planner.js";
 const DC_RUN_TOOL = "dc_run";
 const DC_DIAGRAM_TOOL = "dc_diagram";
-const AUTHORING_INSTRUCTION = `DeepClause programs live in .pi/deepclause/skills/ and executable generated plans live in .pi/deepclause/plans/. You may create and edit DML skills directly after consulting .pi/deepclause/AGENTS.md and DML_REFERENCE.md. Use /dc-plan when the user asks pi to design a contextual executable plan; finish that planning turn with dc_plan_commit. When the user asks for a diagram, flowchart, or visual of a .dml file, call the dc_diagram tool with the exact path and the requested grade (presentation or specification); it writes the viewer under .pi/deepclause/diagrams/ and opens it, so do not hand-write Mermaid. DeepClause compilation is unavailable, so generated content must already be valid DML. Users execute programs through /dc-run. If the opt-in dc_run tool is active, you may execute an ordinary skill with it, but contextual plans requiring pi_agent_step must be started by the user. Never invoke a compiler or create .deepclause/.`;
+const DC_SPEC_GRAPH_TOOL = "dc_spec_graph";
+const AUTHORING_INSTRUCTION = `DeepClause programs live in .pi/deepclause/skills/ and executable generated plans live in .pi/deepclause/plans/. You may create and edit DML skills directly after consulting .pi/deepclause/AGENTS.md and DML_REFERENCE.md. Use /dc-plan when the user asks pi to design a contextual executable plan; finish that planning turn with dc_plan_commit. When the user asks for a diagram, flowchart, or visual of a .dml file, call the dc_diagram tool with the exact path and the requested grade (presentation or specification); it writes the viewer under .pi/deepclause/diagrams/ and opens it, so do not hand-write Mermaid. DeepClause compilation is unavailable, so generated content must already be valid DML. Users execute programs through /dc-run. If the opt-in dc_run tool is active, you may execute an ordinary skill with it, but contextual plans requiring pi_agent_step must be started by the user. Never invoke a compiler or create .deepclause/. Capability specs live in .pi/deepclause/specs/ and change deltas in .pi/deepclause/changes/<slug>/specs/; validate them deterministically with /dc-check, and call dc_spec_graph when the user wants a graph of capabilities, requirements, scenarios or changes.`;
 const STATUS_KEY = "deepclause";
 const WIDGET_KEY = "deepclause-stream";
 export function splitArguments(input) {
@@ -67,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;
         }
@@ -91,34 +94,62 @@ 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);
     let name;
+    let change;
+    let update = false;
     let debug = false;
     const requestParts = [];
     for (let index = 0; index < tokens.length; index++) {
         const token = tokens[index];
         if (token === "--debug" || token === "-d")
             debug = true;
+        else if (token === "--update")
+            update = true;
         else if (token.startsWith("--name="))
             name = token.slice("--name=".length);
         else if (token === "--name")
             name = tokens[++index];
+        else if (token.startsWith("--change="))
+            change = token.slice("--change=".length);
+        else if (token === "--change")
+            change = tokens[++index];
         else
             requestParts.push(token);
     }
+    // allow the leading "update" keyword form: /dc-plan update --change=<slug> <request>
+    if (change && requestParts[0] === "update") {
+        update = true;
+        requestParts.shift();
+    }
     const request = requestParts.join(" ").trim();
     if (!request)
-        throw new Error("Usage: /dc-plan <request> [--name=slug] [--debug]");
+        throw new Error("Usage: /dc-plan <request> [--name=slug] [--change=slug] [--update] [--debug]");
     if (name !== undefined && !name.trim())
         throw new Error("--name requires a non-empty slug");
-    return { request, name: name?.trim(), debug };
+    if (change !== undefined && !change.trim())
+        throw new Error("--change requires a non-empty slug");
+    if (update && !change)
+        throw new Error("--update requires --change=<slug>");
+    return { request, name: name?.trim(), change: change?.trim(), update, debug };
 }
 function messageText(message) {
     if (!message || typeof message !== "object")
@@ -155,6 +186,52 @@ function eventSummary(event, debug) {
         case "memory_compaction": return `compaction ${event.compactionAction ?? "event"}`;
     }
 }
+async function isMutatingSpecSkill(filePath) {
+    try {
+        return /^%\s*Mutating:\s*true\s*$/m.test(await readFile(filePath, "utf8"));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * After a step that leaves the tree dirty, offer to commit it (or remind the user).
+ * A clean tree is what lets the next /dc-apply take a rollback snapshot.
+ */
+export async function offerCommit(pi, ctx, action, change) {
+    let status;
+    try {
+        status = await pi.exec("git", ["status", "--porcelain"], { cwd: ctx.cwd });
+    }
+    catch {
+        return;
+    }
+    if (status.code !== 0)
+        return; // not a repository: nothing to say
+    const files = status.stdout.split("\n").map((line) => line.trim()).filter(Boolean);
+    if (files.length === 0)
+        return; // clean
+    const message = `${action}: ${change}`;
+    const listed = files.slice(0, 12).join("\n");
+    const more = files.length > 12 ? `\n… and ${files.length - 12} more` : "";
+    const reminder = `${files.length} changed file(s):\n${listed}${more}\n\ngit add -A && git commit -m "${message}"`;
+    if (!ctx.hasUI) {
+        ctx.ui.notify(`Uncommitted changes. ${reminder}`, "warning");
+        return;
+    }
+    if (!await ctx.ui.confirm("Commit these changes?", `${reminder}\n\nCommit now?`)) {
+        ctx.ui.notify(`Remember to commit before continuing. ${reminder}`, "warning");
+        return;
+    }
+    await pi.exec("git", ["add", "-A"], { cwd: ctx.cwd });
+    const commit = await pi.exec("git", ["commit", "-m", message], { cwd: ctx.cwd });
+    if (commit.code === 0) {
+        ctx.ui.notify(`Committed: ${message}`, "info");
+    }
+    else {
+        ctx.ui.notify(`Commit failed: ${commit.stderr.trim() || "see git output"}`, "error");
+    }
+}
 async function listDmlFiles(directory, prefix = "") {
     let entries;
     try {
@@ -178,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");
 }
@@ -192,6 +280,7 @@ export default function deepClauseExtension(pi) {
     let activeDescription;
     let modelToolRegistered = false;
     let diagramToolRegistered = false;
+    let specGraphToolRegistered = false;
     let planCommitRegistered = false;
     let planningTransaction;
     let pendingAgentStep;
@@ -219,6 +308,8 @@ export default function deepClauseExtension(pi) {
                         requiredTools: Type.Array(Type.String()),
                         relevantSkills: Type.Array(Type.String()),
                         expectedResult: Type.String(),
+                        satisfies: Type.Optional(Type.Array(Type.String())),
+                        checks: Type.Optional(Type.Array(Type.String())),
                     }), { minItems: 1, maxItems: 12 }),
                     finalSynthesis: Type.Optional(Type.String()),
                     failureMessage: Type.String(),
@@ -238,14 +329,18 @@ export default function deepClauseExtension(pi) {
                         };
                     }
                     try {
-                        const plan = validatePlanSpec(params, transaction.snapshot, transaction.nameOverride);
+                        const plan = validatePlanSpec(params, transaction.snapshot, transaction.nameOverride, {
+                            requireChecks: Boolean(transaction.change),
+                            change: transaction.change,
+                        });
                         const preview = [
                             plan.spec.title,
                             `Objective: ${plan.spec.objective}`,
+                            transaction.change ? `Change: ${transaction.change}` : "",
                             `Steps: ${plan.spec.steps.length}`,
                             `Pi tools: ${plan.requiredTools.join(", ") || "none"}`,
-                            ...plan.spec.steps.map((step, index) => `${index + 1}. [${step.executor}] ${step.title}`),
-                        ].join("\n");
+                            ...plan.spec.steps.map((step, index) => `${index + 1}. [${step.executor}] ${step.title}${step.checks.length ? ` (${step.checks.length} checks)` : ""}`),
+                        ].filter(Boolean).join("\n");
                         if (!ctx.hasUI || !await ctx.ui.confirm("Create executable DeepClause plan?", preview)) {
                             return {
                                 content: [{ type: "text", text: "Plan creation was not approved." }],
@@ -253,15 +348,27 @@ export default function deepClauseExtension(pi) {
                             };
                         }
                         const paths = await initializeWorkspace(ctx.cwd);
-                        const dml = assemblePlanDml(plan, transaction.snapshot);
-                        await validateGeneratedPlan(dml);
-                        const filePath = await writePlanNonDestructively(paths, plan.spec.slug, dml);
+                        const content = transaction.change
+                            ? assembleTasksDml(plan, transaction.snapshot)
+                            : assemblePlanDml(plan, transaction.snapshot);
+                        if (transaction.change)
+                            await validateGeneratedTasks(content);
+                        else
+                            await validateGeneratedPlan(content);
+                        const filePath = transaction.change
+                            ? await writeChangeTasks(paths, normalizePlanSlug(transaction.change), content, Boolean(transaction.update))
+                            : await writePlanNonDestructively(paths, plan.spec.slug, content);
                         transaction.committed = true;
                         setPlanCommitActive(false);
+                        await offerCommit(pi, ctx, "plan", transaction.change ? normalizePlanSlug(transaction.change) : plan.spec.slug);
                         const relativePath = path.relative(paths.root, filePath).split(path.sep).join("/");
                         const text = [
-                            `Created executable DML plan: .pi/deepclause/${relativePath}`,
-                            `Run it with: /dc-run ${relativePath}`,
+                            transaction.change
+                                ? `Created change plan: .pi/deepclause/${relativePath}`
+                                : `Created executable DML plan: .pi/deepclause/${relativePath}`,
+                            transaction.change
+                                ? `Next: /dc-check ${normalizePlanSlug(transaction.change)}`
+                                : `Run it with: /dc-run ${relativePath}`,
                             plan.warnings.length ? `Warnings:\n${plan.warnings.join("\n")}` : "",
                         ].filter(Boolean).join("\n\n");
                         return {
@@ -269,6 +376,7 @@ export default function deepClauseExtension(pi) {
                             details: {
                                 success: true,
                                 path: relativePath,
+                                change: transaction.change,
                                 contextual: plan.spec.steps.some((step) => step.executor === "pi"),
                                 requiredTools: plan.requiredTools,
                                 warnings: plan.warnings,
@@ -604,10 +712,87 @@ export default function deepClauseExtension(pi) {
             pi.setActiveTools([...activeTools, DC_DIAGRAM_TOOL]);
         }
     };
+    const setSpecGraphActive = () => {
+        if (!specGraphToolRegistered) {
+            pi.registerTool({
+                name: DC_SPEC_GRAPH_TOOL,
+                label: "Spec Graph",
+                description: "Create a Mermaid graph of DeepClause capabilities, requirements, scenarios and changes, write a viewer under .pi/deepclause/diagrams/, and open it.",
+                promptSnippet: "Create a capability/change graph from DeepClause spec facts",
+                promptGuidelines: [
+                    "Call dc_spec_graph when the user asks for a graph or visual of capabilities, requirements, changes, or spec coverage.",
+                ],
+                parameters: Type.Object({
+                    view: Type.Optional(StringEnum(["capabilities", "changes"])),
+                }),
+                async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+                    try {
+                        const view = params.view ?? "capabilities";
+                        const mermaid = await runSpecSkill(ctx, "spec_graph", [view]);
+                        const name = `spec-${view}`;
+                        const entry = {
+                            name,
+                            path: `specs (${view})`,
+                            flow: mermaid,
+                            seq: "",
+                            dml: "",
+                            presentation: mermaid,
+                            specification: null,
+                        };
+                        const build = await buildEntriesViewer({
+                            cwd: ctx.cwd,
+                            templateText: await bundledViewerTemplate(),
+                            vendorAssetPath: viewerVendorAssetPath(),
+                            entries: [entry],
+                        });
+                        const opened = ctx.hasUI
+                            ? await openViewerInBrowser(pi, build.viewerPath, name, "presentation")
+                            : false;
+                        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, viewerPath: build.viewerPath, opened },
+                        };
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        return { content: [{ type: "text", text: `dc_spec_graph failed: ${message}` }], details: { success: false, error: message } };
+                    }
+                },
+            });
+            specGraphToolRegistered = true;
+        }
+        const activeTools = pi.getActiveTools();
+        if (!activeTools.includes(DC_SPEC_GRAPH_TOOL)) {
+            pi.setActiveTools([...activeTools, DC_SPEC_GRAPH_TOOL]);
+        }
+    };
+    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}`;
+        try {
+            const result = await executeDml(filePath, args, [], config, pi, ctx, controller, {
+                onEvent() { },
+                onInput: async () => { throw new Error("spec skills do not request input"); },
+            }, options.piAgentStep ? (request, signal) => runPiAgentStep(request, signal, ctx) : undefined, options.verifyCommands ?? [], options.changeJsonPath);
+            if (result.errors.length)
+                throw new Error(result.errors.join("\n"));
+            return result.answer ?? "(no answer)";
+        }
+        finally {
+            activeController = undefined;
+            activeDescription = undefined;
+        }
+    };
     pi.on("session_start", async (_event, ctx) => {
         const config = await loadConfig(getPaths(ctx.cwd).config);
         setModelToolActive(config.modelToolEnabled);
         setDiagramToolActive();
+        setSpecGraphActive();
     });
     pi.on("tool_execution_start", (event) => {
         if (pendingAgentStep && !pendingAgentStep.toolsUsed.includes(event.toolName)) {
@@ -683,17 +868,25 @@ 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;",
                 "it writes the viewer under .pi/deepclause/diagrams/ and opens it.",
                 "Commands:",
                 "  /dc-list",
-                "  /dc-plan <request> [--name=slug]   create an executable contextual DML plan",
-                "  /dc-run <skill|path> [args] [--context=turn|branch|isolated]",
+                "  /dc-plan <request> [--change=slug] [--update] [--name=slug]   create or regenerate a plan",
+                "  /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] [--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");
@@ -711,6 +904,17 @@ export default function deepClauseExtension(pi) {
                 if (!ctx.model)
                     throw new Error("Select a pi model before creating a plan");
                 const paths = await initializeWorkspace(ctx.cwd);
+                if (parsed.change && !parsed.update) {
+                    const changeSlug = normalizePlanSlug(parsed.change);
+                    try {
+                        await access(path.join(paths.changes, changeSlug, "tasks.dml"));
+                        ctx.ui.notify(`changes/${changeSlug}/tasks.dml already exists. Re-run with --update to regenerate it, or edit tasks.dml directly.`, "error");
+                        return;
+                    }
+                    catch {
+                        // no existing plan: proceed
+                    }
+                }
                 const promptOptions = ctx.getSystemPromptOptions();
                 const snapshot = {
                     model: `${ctx.model.provider}/${ctx.model.id}`,
@@ -725,12 +929,18 @@ export default function deepClauseExtension(pi) {
                 planningTransaction = {
                     snapshot,
                     nameOverride: parsed.name,
+                    change: parsed.change,
+                    update: parsed.update,
                     committed: false,
                     startedAt: Date.now(),
                 };
                 setPlanCommitActive(true);
-                ctx.ui.notify("Starting a contextual pi planning turn. Review the generated plan before it is written.", "info");
-                pi.sendUserMessage(buildPlanningPrompt(parsed.request, snapshot, parsed.name));
+                ctx.ui.notify(parsed.change
+                    ? parsed.update
+                        ? `Regenerating the change plan for '${parsed.change}'. Existing artifacts are read first and tasks.dml statuses reset to pending.`
+                        : `Starting a change planning turn for '${parsed.change}'. Review the delta and plan before it is written.`
+                    : "Starting a contextual pi planning turn. Review the generated plan before it is written.", "info");
+                pi.sendUserMessage(buildPlanningPrompt(parsed.request, snapshot, parsed.name, parsed.change, parsed.update));
             }
             catch (error) {
                 planningTransaction = undefined;
@@ -768,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) => {
@@ -794,6 +1071,126 @@ export default function deepClauseExtension(pi) {
             ctx.ui.notify("Cancelling DeepClause execution", "warning");
         },
     });
+    pi.registerCommand("dc-check", {
+        description: "Validate DeepClause specs and change deltas deterministically (no model calls)",
+        handler: async (_rawArgs, ctx) => {
+            if (activeController || !ctx.isIdle()) {
+                ctx.ui.notify("DeepClause or pi is already active; wait before running /dc-check", "warning");
+                return;
+            }
+            try {
+                const answer = await runSpecSkill(ctx, "spec_validate");
+                publishResult(pi, answer, { skill: "spec_validate" });
+                ctx.ui.notify(answer.startsWith("spec check: OK") ? "Spec check passed" : "Spec check reported errors", answer.startsWith("spec check: OK") ? "info" : "warning");
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                publishResult(pi, `Spec check failed: ${message}`, { error: message });
+                ctx.ui.notify(message, "error");
+            }
+        },
+    });
+    pi.registerCommand("dc-archive", {
+        description: "Merge a change delta into specs/ after review, then move the change into changes/archive/",
+        handler: async (rawArgs, ctx) => {
+            if (activeController || !ctx.isIdle()) {
+                ctx.ui.notify("DeepClause or pi is already active; wait before running /dc-archive", "warning");
+                return;
+            }
+            const change = rawArgs.trim();
+            if (!change) {
+                ctx.ui.notify("Usage: /dc-archive <change>", "warning");
+                return;
+            }
+            try {
+                const plan = await runSpecSkill(ctx, "spec_merge", [change]);
+                if (!ctx.hasUI || !await ctx.ui.confirm("Archive change into specs?", plan)) {
+                    ctx.ui.notify("Archive cancelled", "warning");
+                    return;
+                }
+                const applied = await runSpecSkill(ctx, "spec_archive", [change]);
+                const paths = await initializeWorkspace(ctx.cwd);
+                const from = path.join(paths.changes, change);
+                const stamp = new Date().toISOString().slice(0, 10);
+                await mkdir(path.join(paths.changes, "archive"), { recursive: true });
+                let target = path.join(paths.changes, "archive", `${stamp}-${change}`);
+                try {
+                    await access(target);
+                    target = `${target}-2`;
+                }
+                catch {
+                    // target is free
+                }
+                await rename(from, target);
+                const archivedTo = path.relative(ctx.cwd, target).split(path.sep).join("/");
+                publishResult(pi, `${applied}\n\n  moved to ${archivedTo}`, { skill: "spec_archive", change, archivedTo });
+                ctx.ui.notify(`Archived ${change}`, "info");
+                await offerCommit(pi, ctx, "archive", change);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                publishResult(pi, `Archive failed: ${message}`, { error: message });
+                ctx.ui.notify(message, "error");
+            }
+        },
+    });
+    pi.registerCommand("dc-apply", {
+        description: "Execute a change's tasks.dml with per-task verification and bounded retries",
+        handler: async (rawArgs, ctx) => {
+            if (activeController || !ctx.isIdle()) {
+                ctx.ui.notify("DeepClause or pi is already active; wait before running /dc-apply", "warning");
+                return;
+            }
+            const tokens = splitArguments(rawArgs);
+            const abort = tokens.includes("--abort");
+            const change = tokens.filter((token) => token !== "--abort").join(" ").trim();
+            if (!change) {
+                ctx.ui.notify("Usage: /dc-apply <change> [--abort]", "warning");
+                return;
+            }
+            try {
+                const paths = await initializeWorkspace(ctx.cwd);
+                const changeJson = path.join(paths.changes, change, "change.json");
+                if (abort) {
+                    const restored = await gitRestore(pi, ctx.cwd, changeJson).catch(() => null);
+                    const message = restored
+                        ? `Discarded the apply and restored the working tree to ${restored}.`
+                        : "No recorded apply snapshot to discard.";
+                    publishResult(pi, message, { skill: "spec_apply", change, aborted: Boolean(restored) });
+                    ctx.ui.notify(message, restored ? "warning" : "info");
+                    return;
+                }
+                let started = false;
+                let succeeded = false;
+                try {
+                    const plan = await runSpecSkill(ctx, "spec_apply", [change, "plan"]);
+                    const commands = [...new Set([...plan.matchAll(/^command:\s*(.+)$/gm)].map((match) => match[1].trim()))];
+                    const preview = [plan, "", `Approved verification commands: ${commands.join(", ") || "none"}`].join("\n");
+                    if (!ctx.hasUI || !await ctx.ui.confirm("Apply change tasks?", preview)) {
+                        ctx.ui.notify("Apply cancelled", "warning");
+                        return;
+                    }
+                    started = true;
+                    const answer = await runSpecSkill(ctx, "spec_apply", [change, "apply"], { verifyCommands: commands, piAgentStep: true, changeJsonPath: changeJson });
+                    succeeded = answer.includes("status: OK");
+                    publishResult(pi, answer, { skill: "spec_apply", change });
+                    ctx.ui.notify(succeeded ? `Applied ${change}` : `Apply incomplete for ${change}`, succeeded ? "info" : "warning");
+                }
+                finally {
+                    if (started && !succeeded) {
+                        ctx.ui.notify(`Apply interrupted; the working tree and task statuses were preserved. Resume with /dc-apply ${change}, or discard with /dc-apply ${change} --abort.`, "warning");
+                    }
+                }
+                if (succeeded)
+                    await offerCommit(pi, ctx, "apply", change);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                publishResult(pi, `Apply failed: ${message}`, { error: message });
+                ctx.ui.notify(message, "error");
+            }
+        },
+    });
     pi.registerCommand("dc-run", {
         description: "Run a DML skill with pi's active model",
         handler: async (rawArgs, ctx) => {
@@ -806,6 +1203,10 @@ export default function deepClauseExtension(pi) {
                 const paths = await initializeWorkspace(ctx.cwd);
                 const config = await loadConfig(paths.config);
                 const filePath = await resolveDmlPath(paths, parsed.target);
+                if (await isMutatingSpecSkill(filePath)) {
+                    ctx.ui.notify(`${parsed.target} modifies specs/. Use /dc-archive <change> so you can review the merge first.`, "warning");
+                    return;
+                }
                 const contextualPlan = await isContextualPlan(filePath);
                 if (contextualPlan) {
                     const requiredTools = await readPlanRequiredTools(filePath);
@@ -904,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) => {