deepclause-pi 0.1.5 → 0.3.0

package/src/index.ts

@@ -1,28 +1,53 @@
-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 type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 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 { executeDml } from "./runtime.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";
+import {
+  buildEntriesViewer,
+  buildViewer,
+  openViewerInBrowser,
+  writeSidecar,
+  type DiagramEntry,
+} 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,
+  assembleTasksDml,
   buildPlanningPrompt,
   DC_PLAN_COMMIT_TOOL,
   isContextualPlan,
+  normalizePlanSlug,
   PI_AGENT_STEP_TOOL,
   readPlanRequiredTools,
   validateGeneratedPlan,
+  validateGeneratedTasks,
   validatePlanSpec,
+  writeChangeTasks,
   writePlanNonDestructively,
   type PlanningSnapshot,
 } 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";
 
@@ -37,12 +62,16 @@ export interface ParsedRun {
 interface ParsedPlan {
   request: string;
   name?: string;
+  change?: string;
+  update?: boolean;
   debug: boolean;
 }
 
 interface PlanningTransaction {
   snapshot: PlanningSnapshot;
   nameOverride?: string;
+  change?: string;
+  update?: boolean;
   committed: boolean;
   startedAt: number;
 }
@@ -127,19 +156,31 @@ export function parseRun(input: string): ParsedRun {
 export function parsePlan(input: string): ParsedPlan {
   const tokens = splitArguments(input);
   let name: string | undefined;
+  let change: string | undefined;
+  let update = false;
   let debug = false;
   const requestParts: string[] = [];
   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]");
+  if (!request) 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: unknown): string {
@@ -176,6 +217,56 @@ function eventSummary(event: DMLEvent, debug: boolean): string {
   }
 }
 
+async function isMutatingSpecSkill(filePath: string): Promise<boolean> {
+  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: ExtensionAPI,
+  ctx: ExtensionContext,
+  action: string,
+  change: string,
+): Promise<void> {
+  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: string, prefix = ""): Promise<string[]> {
   let entries;
   try {
@@ -197,6 +288,14 @@ function modelLabel(ctx: ExtensionCommandContext): string {
   return ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "none selected";
 }
 
+async function bundledViewerTemplate(): Promise<string> {
+  return readFile(fileURLToPath(new URL("./assets/viewer.template.html", import.meta.url)), "utf8");
+}
+
+function viewerVendorAssetPath(): string {
+  return fileURLToPath(new URL("./assets/vendor/mermaid.min.js", import.meta.url));
+}
+
 function publishResult(pi: ExtensionAPI, content: string, details: Record<string, unknown>): void {
   pi.sendMessage({ customType: "deepclause-result", content, display: true, details });
 }
@@ -205,6 +304,8 @@ export default function deepClauseExtension(pi: ExtensionAPI) {
   let activeController: AbortController | undefined;
   let activeDescription: string | undefined;
   let modelToolRegistered = false;
+  let diagramToolRegistered = false;
+  let specGraphToolRegistered = false;
   let planCommitRegistered = false;
   let planningTransaction: PlanningTransaction | undefined;
   let pendingAgentStep: PendingAgentStep | undefined;
@@ -233,6 +334,8 @@ export default function deepClauseExtension(pi: ExtensionAPI) {
             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(),
@@ -253,14 +356,18 @@ export default function deepClauseExtension(pi: ExtensionAPI) {
           }
 
           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." }],
@@ -269,15 +376,25 @@ export default function deepClauseExtension(pi: ExtensionAPI) {
             }
 
             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 {
@@ -285,6 +402,7 @@ export default function deepClauseExtension(pi: ExtensionAPI) {
               details: {
                 success: true,
                 path: relativePath,
+                change: transaction.change,
                 contextual: plan.spec.steps.some((step) => step.executor === "pi"),
                 requiredTools: plan.requiredTools,
                 warnings: plan.warnings,
@@ -507,9 +625,228 @@ export default function deepClauseExtension(pi: ExtensionAPI) {
     }
   };
 
+  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"] as const, { 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: DiagramGrade[] = requested === "both" ? ["presentation", "specification"] : [requested];
+          const view: MermaidView = params.view === "sequence" ? "sequence" : "flow";
+
+          let sourcePath: string;
+          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: string, args: string[], options?: { timeout?: number }) => pi.exec(command, args, options);
+          let chrome: string | undefined;
+          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"] as const)),
+        }),
+        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: DiagramEntry = {
+              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: ExtensionContext,
+    skill: string,
+    args: string[] = [],
+    options: { verifyCommands?: string[]; piAgentStep?: boolean; changeJsonPath?: string } = {},
+  ): Promise<string> => {
+    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) => {
@@ -590,9 +927,15 @@ export default function deepClauseExtension(pi: ExtensionAPI) {
         `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",
@@ -614,6 +957,16 @@ export default function deepClauseExtension(pi: ExtensionAPI) {
         const parsed = parsePlan(rawArgs);
         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: PlanningSnapshot = {
           model: `${ctx.model.provider}/${ctx.model.id}`,
@@ -628,12 +981,21 @@ export default function deepClauseExtension(pi: ExtensionAPI) {
         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;
         setPlanCommitActive(false);
@@ -698,6 +1060,131 @@ export default function deepClauseExtension(pi: ExtensionAPI) {
     },
   });
 
+  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) => {
@@ -712,6 +1199,10 @@ export default function deepClauseExtension(pi: ExtensionAPI) {
         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);