deepclause-pi 0.2.0 → 0.3.0

package/README.md

@@ -131,6 +131,19 @@ The resulting `.dml` file is the plan. Steps use one of two executors:
 
 For each pi step, only the exact tools named in the committed plan are temporarily active. They must still be installed and active when execution begins; existing tool policies, UI, and approvals remain authoritative. DeepClause control tools cannot be requested recursively. The prior active-tool set is restored after success, failure, or cancellation.
 
+## deepclause-pi speckit
+
+Spec-driven changes, built on the same runtime: behaviour specs in plain Markdown, reviewable change deltas, and an executable `tasks.dml` that pi runs with deterministic validation, per-task verification, rollback and resume.
+
+```text
+/dc-plan <request> --change=<slug>   propose
+/dc-check <slug>                     validate (0 tokens)
+/dc-apply <slug>                     execute, verify, retry, resume
+/dc-archive <slug>                   merge into specs/
+```
+
+See the [deepclause-pi speckit guide](docs/SPECKIT.md) for the getting-started walkthrough and reference.
+
 ## Diagrams
 
 Ask pi for a diagram of any DML file in plain language:

package/dist/diagram/viewer.d.ts

@@ -25,6 +25,12 @@ export interface BuildViewerOptions {
  * sidecars, and write the self-contained viewer plus per-skill Markdown.
  */
 export declare function buildViewer(options: BuildViewerOptions): Promise<ViewerBuildResult>;
+export declare function buildEntriesViewer(options: {
+    cwd: string;
+    templateText: string;
+    vendorAssetPath: string;
+    entries: DiagramEntry[];
+}): Promise<ViewerBuildResult>;
 export declare function writeSidecar(diagramsDir: string, name: string, grade: DiagramGrade, code: string): Promise<string>;
 /** Open the viewer at a specific diagram and view using a fixed, OS-native argv. */
 export declare function openViewerInBrowser(pi: Pick<ExtensionAPI, "exec">, viewerPath: string, name: string, view: string): Promise<boolean>;

package/dist/diagram/viewer.js

@@ -71,6 +71,11 @@ export async function buildViewer(options) {
     const viewerPath = await renderViewer(diagrams, entries, options.templateText, vendorFile);
     return { viewerPath, diagramsDir: diagrams, entries };
 }
+export async function buildEntriesViewer(options) {
+    const { diagrams, vendorFile } = await ensureDiagramDir(options.cwd, options.vendorAssetPath);
+    const viewerPath = await renderViewer(diagrams, options.entries, options.templateText, vendorFile);
+    return { viewerPath, diagramsDir: diagrams, entries: options.entries };
+}
 export async function writeSidecar(diagramsDir, name, grade, code) {
     const file = path.join(diagramsDir, `${name}.${grade}.mmd`);
     await writeFile(file, code.endsWith("\n") ? code : `${code}\n`, "utf8");

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type ContextMode } from "./config.js";
 export interface ParsedRun {
     target: string;
@@ -10,10 +10,17 @@ export interface ParsedRun {
 interface ParsedPlan {
     request: string;
     name?: string;
+    change?: string;
+    update?: boolean;
     debug: boolean;
 }
 export declare function splitArguments(input: string): string[];
 export declare function parseRun(input: string): ParsedRun;
 export declare function parsePlan(input: string): ParsedPlan;
+/**
+ * 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 declare function offerCommit(pi: ExtensionAPI, ctx: ExtensionContext, action: string, change: string): Promise<void>;
 export default function deepClauseExtension(pi: ExtensionAPI): void;
 export {};

package/dist/index.js

@@ -1,4 +1,4 @@
-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";
@@ -8,15 +8,16 @@ import { loadConfig, 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) {
@@ -100,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")
@@ -155,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 {
@@ -192,6 +256,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 +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(),
@@ -238,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." }],
@@ -253,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 {
@@ -269,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,
@@ -604,10 +688,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, 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)) {
@@ -689,7 +850,10 @@ export default function deepClauseExtension(pi) {
                 "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",
@@ -711,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}`,
@@ -725,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;
@@ -794,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) => {
@@ -806,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/planner.d.ts

@@ -10,6 +10,8 @@ export interface PlanStepSpec {
     requiredTools: string[];
     relevantSkills: string[];
     expectedResult: string;
+    satisfies: string[];
+    checks: string[];
 }
 export interface PlanSpec {
     slug: string;
@@ -19,6 +21,11 @@ export interface PlanSpec {
     steps: PlanStepSpec[];
     finalSynthesis?: string;
     failureMessage: string;
+    change?: string;
+}
+export interface ValidatePlanOptions {
+    requireChecks?: boolean;
+    change?: string;
 }
 export interface PlanningSnapshot {
     model: string;
@@ -36,10 +43,28 @@ export interface ValidatedPlan {
     warnings: string[];
 }
 export declare function normalizePlanSlug(value: string): string;
-export declare function validatePlanSpec(value: unknown, snapshot: PlanningSnapshot, nameOverride?: string): ValidatedPlan;
+export declare function validatePlanSpec(value: unknown, snapshot: PlanningSnapshot, nameOverride?: string, options?: ValidatePlanOptions): ValidatedPlan;
+export interface ParsedCheck {
+    kind: "cmd" | "exists" | "model";
+    value: string;
+}
+/** Parse an encoded verification check: cmd:<command>, exists:<path>, model:<question>. */
+export declare function parseCheck(encoded: string): ParsedCheck;
+/**
+ * Assemble the `tasks.dml` data artifact for a change: plan_task/2 definitions plus
+ * the managed plan_task_status/2 block. Verified by /dc-check and executed by /dc-apply.
+ */
+export declare function assembleTasksDml(plan: ValidatedPlan, snapshot: PlanningSnapshot): string;
+/** Write changes/<slug>/tasks.dml, refusing to clobber an existing plan unless overwrite=true. */
+export declare function writeChangeTasks(paths: DeepClausePaths, slug: string, text: string, overwrite?: boolean): Promise<string>;
 export declare function assemblePlanDml(plan: ValidatedPlan, snapshot: PlanningSnapshot): string;
 export declare function validateGeneratedPlan(dml: string): Promise<void>;
+/**
+ * Data-only artifact (tasks.dml): no agent_main of its own, so validation appends a
+ * trivial entry point to parse the facts without changing what is written.
+ */
+export declare function validateGeneratedTasks(dml: string): Promise<void>;
 export declare function writePlanNonDestructively(paths: DeepClausePaths, slug: string, dml: string): Promise<string>;
 export declare function isContextualPlan(filePath: string): Promise<boolean>;
 export declare function readPlanRequiredTools(filePath: string): Promise<string[]>;
-export declare function buildPlanningPrompt(request: string, snapshot: PlanningSnapshot, nameOverride?: string): string;
+export declare function buildPlanningPrompt(request: string, snapshot: PlanningSnapshot, nameOverride?: string, change?: string, update?: boolean): string;