deepclause-pi 0.1.5 → 0.3.0

package/dist/index.js

@@ -1,14 +1,23 @@
-import { 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 { executeDml } from "./runtime.js";
+import { renderDml, renderSequence } from "./diagram/extract.js";
+import { polishDiagram, resolveGrade } from "./diagram/grade.js";
+import { findChrome, validateMermaid } from "./diagram/validate.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, 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 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. 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_DIAGRAM_TOOL = "dc_diagram";
+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) {
@@ -92,25 +101,42 @@ export function parseRun(input) {
 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")
@@ -147,6 +173,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 {
@@ -170,6 +242,12 @@ async function listDmlFiles(directory, prefix = "") {
 function modelLabel(ctx) {
     return ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "none selected";
 }
+async function bundledViewerTemplate() {
+    return readFile(fileURLToPath(new URL("./assets/viewer.template.html", import.meta.url)), "utf8");
+}
+function viewerVendorAssetPath() {
+    return fileURLToPath(new URL("./assets/vendor/mermaid.min.js", import.meta.url));
+}
 function publishResult(pi, content, details) {
     pi.sendMessage({ customType: "deepclause-result", content, display: true, details });
 }
@@ -177,6 +255,8 @@ export default function deepClauseExtension(pi) {
     let activeController;
     let activeDescription;
     let modelToolRegistered = false;
+    let diagramToolRegistered = false;
+    let specGraphToolRegistered = false;
     let planCommitRegistered = false;
     let planningTransaction;
     let pendingAgentStep;
@@ -204,6 +284,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(),
@@ -223,14 +305,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." }],
@@ -238,15 +324,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 {
@@ -254,6 +352,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,
@@ -468,9 +567,208 @@ export default function deepClauseExtension(pi) {
                 : activeTools.filter((name) => name !== DC_RUN_TOOL));
         }
     };
+    const setDiagramToolActive = () => {
+        if (!diagramToolRegistered) {
+            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.",
+                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.",
+                    "Do not hand-write Mermaid or run diagram tools yourself; call dc_diagram and report the viewer result.",
+                ],
+                parameters: Type.Object({
+                    dml: Type.String({ description: "Path to a .dml file, relative to the workspace or absolute. A leading @ is ignored." }),
+                    grade: Type.Optional(Type.String({ description: "presentation (default), specification, or both. Synonyms such as detailed or technical map to specification." })),
+                    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) {
+                        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 {
+                        for (const grade of grades) {
+                            const result = await polishDiagram({
+                                grade,
+                                view,
+                                source,
+                                seed,
+                                maxTokens: config.maxTokens,
+                                signal: controller.signal,
+                                complete: (options) => completeTextWithPiModel(ctx, options),
+                                validate: async (code) => {
+                                    if (!chromeResolved) {
+                                        chrome = await findChrome(run);
+                                        chromeResolved = true;
+                                    }
+                                    const outcome = await validateMermaid(code, view, { run, vendorDir: vendor, chrome: chrome ?? null });
+                                    return outcome.result;
+                                },
+                                onProgress: (message) => onUpdate?.({
+                                    content: [{ type: "text", text: message }],
+                                    details: { dml: display, grades, name },
+                                }),
+                            });
+                            await writeSidecar(diagrams, name, grade, result.code);
+                        }
+                        const build = await buildViewer({
+                            cwd: ctx.cwd,
+                            templateText,
+                            vendorAssetPath: viewerVendorAssetPath(),
+                            extraPaths: [sourcePath],
+                        });
+                        const opened = ctx.hasUI
+                            ? await openViewerInBrowser(pi, build.viewerPath, name, grades[0] ?? "presentation")
+                            : false;
+                        const viewer = displayPath(ctx.cwd, build.viewerPath);
+                        const text = `Created ${grades.join(" + ")}-grade diagram for ${display}. Viewer: ${viewer}${opened ? " (opened in your browser)" : ""}`;
+                        return {
+                            content: [{ type: "text", text }],
+                            details: { success: true, dml: display, grades, name, viewer, opened, chrome: Boolean(chrome) },
+                        };
+                    }
+                    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 } };
+                    }
+                    finally {
+                        signal?.removeEventListener("abort", cancel);
+                        activeController = undefined;
+                        activeDescription = undefined;
+                    }
+                },
+            });
+            diagramToolRegistered = true;
+        }
+        const activeTools = pi.getActiveTools();
+        if (!activeTools.includes(DC_DIAGRAM_TOOL)) {
+            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, 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)) {
@@ -547,9 +845,15 @@ export default function deepClauseExtension(pi) {
                 `Plans: ${path.relative(ctx.cwd, paths.plans)}`,
                 `Context: ${config.contextMode} (verbose default: ${config.verbose})`,
                 `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-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]",
                 "  /dc-run <skill|path> --verbose   show lifecycle events",
                 "  /dc-run <skill|path> --debug     show full event payloads and SDK diagnostics",
@@ -571,6 +875,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}`,
@@ -585,12 +900,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;
@@ -654,6 +975,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) => {
@@ -666,6 +1107,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);

package/dist/model.d.ts

@@ -0,0 +1,16 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Usage } from "@earendil-works/pi-ai";
+export interface TextCompletion {
+    text: string;
+    usage?: Usage;
+}
+/**
+ * One-shot text completion through pi's active model and credentials. Used by
+ * diagram grading; it never requests API keys or mutates provider state.
+ */
+export declare function completeTextWithPiModel(ctx: ExtensionContext, options: {
+    systemPrompt?: string;
+    prompt: string;
+    maxTokens: number;
+    signal?: AbortSignal;
+}): Promise<TextCompletion>;