deepclause-pi 0.1.5 → 0.3.0

package/dist/model.js

@@ -0,0 +1,28 @@
+/**
+ * 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 async function completeTextWithPiModel(ctx, options) {
+    const model = ctx.model;
+    if (!model)
+        throw new Error("Select a pi model before generating a diagram grade");
+    if (!ctx.modelRegistry.hasConfiguredAuth(model)) {
+        throw new Error(`Pi has no configured authentication for ${model.provider}/${model.id}`);
+    }
+    const response = await ctx.modelRegistry.complete(model, {
+        systemPrompt: options.systemPrompt,
+        messages: [{ role: "user", content: options.prompt, timestamp: Date.now() }],
+    }, {
+        signal: options.signal,
+        maxTokens: options.maxTokens,
+        cacheRetention: "none",
+    });
+    if (response.stopReason === "error" || response.stopReason === "aborted") {
+        throw new Error(response.errorMessage || `Pi model request ${response.stopReason}`);
+    }
+    const text = response.content
+        .filter((content) => content.type === "text")
+        .map((content) => content.text)
+        .join("");
+    return { text, usage: response.usage };
+}

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;

package/dist/planner.js

@@ -31,7 +31,7 @@ export function normalizePlanSlug(value) {
         throw new Error("Plan slug must contain a letter or digit");
     return slug;
 }
-export function validatePlanSpec(value, snapshot, nameOverride) {
+export function validatePlanSpec(value, snapshot, nameOverride, options = {}) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         throw new Error("Plan specification must be an object");
     const raw = value;
@@ -48,8 +48,8 @@ export function validatePlanSpec(value, snapshot, nameOverride) {
             throw new Error(`steps[${index}] must be an object`);
         const step = entry;
         const id = requireText(step.id ?? `step_${index + 1}`, `steps[${index}].id`, 80);
-        if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(id))
-            throw new Error(`steps[${index}].id must be a simple identifier`);
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(id))
+            throw new Error(`steps[${index}].id must be a simple identifier (letters, digits, dot, dash, underscore)`);
         if (ids.has(id))
             throw new Error(`Duplicate plan step id: ${id}`);
         ids.add(id);
@@ -58,6 +58,13 @@ export function validatePlanSpec(value, snapshot, nameOverride) {
             throw new Error(`steps[${index}].executor must be pi or dml`);
         const requiredTools = stringArray(step.requiredTools, `steps[${index}].requiredTools`, 16);
         const relevantSkills = stringArray(step.relevantSkills, `steps[${index}].relevantSkills`, 16);
+        const satisfies = stringArray(step.satisfies, `steps[${index}].satisfies`, 32);
+        const checks = stringArray(step.checks, `steps[${index}].checks`, 16);
+        for (const check of checks)
+            parseCheck(check);
+        if (options.requireChecks && checks.length === 0) {
+            throw new Error(`Plan step ${id} must declare at least one verification check (cmd:..., exists:... or model:...)`);
+        }
         if (executor === "dml" && requiredTools.length > 0) {
             throw new Error(`DML step ${id} cannot request pi tools; use executor=pi`);
         }
@@ -81,6 +88,8 @@ export function validatePlanSpec(value, snapshot, nameOverride) {
             requiredTools: [...new Set(requiredTools)],
             relevantSkills: [...new Set(relevantSkills)],
             expectedResult: requireText(step.expectedResult, `steps[${index}].expectedResult`, 1_000),
+            satisfies: [...new Set(satisfies)],
+            checks: [...new Set(checks)],
         };
     });
     const spec = {
@@ -93,6 +102,7 @@ export function validatePlanSpec(value, snapshot, nameOverride) {
             ? requireText(raw.finalSynthesis, "finalSynthesis", 2_000)
             : undefined,
         failureMessage: requireText(raw.failureMessage, "failureMessage", 1_000),
+        change: options.change ? normalizePlanSlug(options.change) : undefined,
     };
     return {
         spec,
@@ -109,6 +119,71 @@ function dmlStringList(values) {
 function commentText(value) {
     return value.replace(/[\r\n]+/g, " ").replace(/%/g, "percent").trim();
 }
+/** Parse an encoded verification check: cmd:<command>, exists:<path>, model:<question>. */
+export function parseCheck(encoded) {
+    const separator = encoded.indexOf(":");
+    if (separator <= 0)
+        throw new Error(`Check must be cmd:..., exists:... or model:...; got '${encoded}'`);
+    const kind = encoded.slice(0, separator).trim();
+    const value = encoded.slice(separator + 1).trim();
+    if (kind !== "cmd" && kind !== "exists" && kind !== "model")
+        throw new Error(`Unknown check kind '${kind}' in '${encoded}'`);
+    if (!value)
+        throw new Error(`Check '${encoded}' has an empty value`);
+    return { kind, value };
+}
+/**
+ * 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 function assembleTasksDml(plan, snapshot) {
+    const { spec } = plan;
+    const taskBlocks = spec.steps.map((step) => {
+        const checks = step.checks.map((encoded) => {
+            const { kind, value } = parseCheck(encoded);
+            return `${kind}(${dmlString(value)})`;
+        });
+        return [
+            `plan_task(${dmlString(step.id)}, task{`,
+            `    executor:  ${step.executor},`,
+            `    do:        ${dmlString(step.instruction)},`,
+            `    tools:     ${dmlStringList(step.requiredTools)},`,
+            `    expected:  ${dmlString(step.expectedResult)},`,
+            `    satisfies: ${dmlStringList(step.satisfies)},`,
+            `    checks:    [${checks.join(", ")}]`,
+            `}).`,
+        ].join("\n");
+    });
+    const statusLines = spec.steps.map((step) => `plan_task_status(${dmlString(step.id)}, pending).`);
+    const metadata = [
+        "% tasks.dml — generated by /dc-plan. Edit conservatively.",
+        `% Change: ${commentText(spec.change ?? spec.slug)}`,
+        `% Title: ${commentText(spec.title)}`,
+        `% Planning model: ${commentText(snapshot.model)}`,
+        `% Required pi tools: ${plan.requiredTools.join(", ") || "none"}`,
+    ].join("\n");
+    return `${metadata}\n\n${taskBlocks.join("\n\n")}\n\n% --- execution state (managed by apply.dml; do not edit by hand) ---\n${statusLines.join("\n")}\n`;
+}
+/** Write changes/<slug>/tasks.dml, refusing to clobber an existing plan unless overwrite=true. */
+export async function writeChangeTasks(paths, slug, text, overwrite = false) {
+    const dir = path.join(paths.changes, slug);
+    await mkdir(dir, { recursive: true });
+    const filePath = path.join(dir, "tasks.dml");
+    if (overwrite) {
+        await writeFile(filePath, text, { encoding: "utf8" });
+        return filePath;
+    }
+    try {
+        await writeFile(filePath, text, { encoding: "utf8", flag: "wx" });
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            throw new Error(`changes/${slug}/tasks.dml already exists; re-run with --update to regenerate it`);
+        }
+        throw error;
+    }
+    return filePath;
+}
 export function assemblePlanDml(plan, snapshot) {
     const { spec } = plan;
     const resultVariables = [];
@@ -167,6 +242,17 @@ export async function validateGeneratedPlan(dml) {
     if (!validation.valid)
         throw new Error(`Generated DML failed validation: ${validation.errors.join("; ")}`);
 }
+/**
+ * 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 async function validateGeneratedTasks(dml) {
+    if (dml.includes(".deepclause/"))
+        throw new Error("Generated tasks may not reference .deepclause/");
+    const validation = await validateWithProlog(`${dml}\nagent_main :- true.\n`);
+    if (!validation.valid)
+        throw new Error(`Generated tasks.dml failed validation: ${validation.errors.join("; ")}`);
+}
 export async function writePlanNonDestructively(paths, slug, dml) {
     await mkdir(paths.plans, { recursive: true });
     for (let suffix = 1; suffix <= 100; suffix++) {
@@ -193,7 +279,7 @@ export async function readPlanRequiredTools(filePath) {
         return [];
     return [...new Set(match[1].split(",").map((name) => name.trim()).filter(Boolean))];
 }
-export function buildPlanningPrompt(request, snapshot, nameOverride) {
+export function buildPlanningPrompt(request, snapshot, nameOverride, change, update = false) {
     const tools = snapshot.allTools.map((tool) => ({
         name: tool.name,
         active: snapshot.activeTools.includes(tool.name),
@@ -202,6 +288,24 @@ export function buildPlanningPrompt(request, snapshot, nameOverride) {
         guidelines: tool.promptGuidelines ?? [],
         source: tool.sourceInfo,
     }));
+    const changeInstructions = change
+        ? [
+            update
+                ? `This regenerates the change '${change}'. Read the existing .pi/deepclause/changes/${change}/proposal.md, specs/**, design.md and tasks.dml first, then revise them as needed.`
+                : `This plan is for the change '${change}'. Before committing, create .pi/deepclause/changes/${change}/ with normal file tools:`,
+            ...(update
+                ? []
+                : [
+                    "- proposal.md — why / what / capabilities / impact.",
+                    "- specs/<capability>.spec.md — delta(s) using ## ADDED|MODIFIED|REMOVED Requirements.",
+                    "- design.md — optional approach and trade-offs.",
+                ]),
+            "Specs describe behaviour only: no commands, file paths, library choices or implementation steps.",
+            "Use exactly three hashes for ### Requirement and four for #### Scenario; every requirement needs at least one scenario.",
+            "Each committed step must list the scenario ids it satisfies (capability#scenario-slug) and at least one check encoded as cmd:<command>, exists:<path> or model:<question>.",
+            "The committed tasks.dml replaces any previous one; every plan_task_status entry resets to pending.",
+        ]
+        : [];
     return [
         "Create an executable DeepClause plan for the request below.",
         "You are in a normal pi turn: inspect the workspace and use currently active tools when that materially improves the plan.",
@@ -211,6 +315,7 @@ export function buildPlanningPrompt(request, snapshot, nameOverride) {
         "Choose executor='dml' for contained reasoning that needs no pi tool; requiredTools must then be empty.",
         "Use only exact active tool names. Never request dc_run, dc_plan_commit, or pi_agent_step.",
         "Keep steps bounded, concrete, ordered, and independently observable. Prefer 3-8 steps.",
+        ...changeInstructions,
         nameOverride ? `The user requested the plan filename slug: ${nameOverride}` : "Choose a concise lowercase slug.",
         `User request:\n${request}`,
         `Current model: ${snapshot.model}; thinking level: ${snapshot.thinkingLevel}`,

package/dist/runtime.d.ts

@@ -3,6 +3,20 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import type { DeepClauseConfig } from "./config.js";
 export declare const PI_WORKSPACE_LIST_TOOL = "pi_workspace_list";
 export declare const PI_BASH_TOOL = "pi_bash";
+export declare const DC_VERIFY_RUN_TOOL = "dc_verify_run";
+export declare const DC_APPLY_SNAPSHOT_TOOL = "dc_apply_snapshot";
+export declare const DC_APPLY_ACCEPT_TOOL = "dc_apply_accept";
+export declare const DC_APPLY_RESTORE_TOOL = "dc_apply_restore";
+/**
+ * Record a git snapshot ref, refusing a dirty working tree. If an apply is already
+ * in progress for this change, the existing ref is returned so the run resumes
+ * instead of starting over or rejecting the (intentionally) dirty tree.
+ */
+export declare function gitSnapshot(pi: Pick<ExtensionAPI, "exec">, cwd: string, changeJsonPath: string): Promise<string>;
+/** Restore the recorded snapshot (hard reset plus clean of untracked files). */
+export declare function gitRestore(pi: Pick<ExtensionAPI, "exec">, cwd: string, changeJsonPath: string): Promise<string | null>;
+/** Mark the apply accepted and clear the snapshot. */
+export declare function gitAccept(changeJsonPath: string): Promise<void>;
 export type BashApproval = (command: string, signal: AbortSignal) => Promise<boolean>;
 export declare function registerPiRuntimeTools(sdk: DeepClauseSDK, pi: Pick<ExtensionAPI, "exec">, cwd: string, signal: AbortSignal, approveBash?: BashApproval): void;
 export interface ExecutionCallbacks {
@@ -27,4 +41,4 @@ export interface ExecutionResult {
     errors: string[];
     usage: LLMUsage;
 }
-export declare function executeDml(filePath: string, args: string[], initialMessages: MemoryMessage[], config: DeepClauseConfig, pi: ExtensionAPI, ctx: ExtensionContext, controller: AbortController, callbacks: ExecutionCallbacks, runPiAgentStep?: (request: PiAgentStepRequest, signal: AbortSignal) => Promise<PiAgentStepResult>): Promise<ExecutionResult>;
+export declare function executeDml(filePath: string, args: string[], initialMessages: MemoryMessage[], config: DeepClauseConfig, pi: ExtensionAPI, ctx: ExtensionContext, controller: AbortController, callbacks: ExecutionCallbacks, runPiAgentStep?: (request: PiAgentStepRequest, signal: AbortSignal) => Promise<PiAgentStepResult>, verifyCommands?: string[], applyChangeJsonPath?: string): Promise<ExecutionResult>;

package/dist/runtime.js

@@ -1,9 +1,71 @@
-import { realpath, readFile } from "node:fs/promises";
+import { realpath, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { createDeepClause } from "deepclause-sdk";
 import { PI_AGENT_STEP_TOOL } from "./planner.js";
 export const PI_WORKSPACE_LIST_TOOL = "pi_workspace_list";
 export const PI_BASH_TOOL = "pi_bash";
+export const DC_VERIFY_RUN_TOOL = "dc_verify_run";
+export const DC_APPLY_SNAPSHOT_TOOL = "dc_apply_snapshot";
+export const DC_APPLY_ACCEPT_TOOL = "dc_apply_accept";
+export const DC_APPLY_RESTORE_TOOL = "dc_apply_restore";
+async function readChangeJson(changeJsonPath) {
+    try {
+        const parsed = JSON.parse(await readFile(changeJsonPath, "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+async function patchChangeJson(changeJsonPath, patch) {
+    let existing = {};
+    try {
+        const parsed = JSON.parse(await readFile(changeJsonPath, "utf8"));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+            existing = parsed;
+    }
+    catch {
+        // start a fresh manifest
+    }
+    await writeFile(changeJsonPath, `${JSON.stringify({ ...existing, ...patch }, null, 2)}\n`, "utf8");
+}
+/**
+ * Record a git snapshot ref, refusing a dirty working tree. If an apply is already
+ * in progress for this change, the existing ref is returned so the run resumes
+ * instead of starting over or rejecting the (intentionally) dirty tree.
+ */
+export async function gitSnapshot(pi, cwd, changeJsonPath) {
+    const existing = await readChangeJson(changeJsonPath);
+    const resumable = typeof existing.snapshot === "string" && existing.snapshot && existing.applyState === "in_progress";
+    if (resumable)
+        return existing.snapshot;
+    const status = await pi.exec("git", ["status", "--porcelain"], { cwd });
+    if (status.code !== 0)
+        throw new Error("git is unavailable or this is not a repository");
+    if (status.stdout.trim())
+        throw new Error("working tree is dirty; commit or stash before applying, or resume with /dc-apply (which preserves an interrupted apply)");
+    const head = await pi.exec("git", ["rev-parse", "HEAD"], { cwd });
+    if (head.code !== 0)
+        throw new Error("could not read git HEAD");
+    const ref = head.stdout.trim();
+    await patchChangeJson(changeJsonPath, { snapshot: ref, applyState: "in_progress" });
+    return ref;
+}
+/** Restore the recorded snapshot (hard reset plus clean of untracked files). */
+export async function gitRestore(pi, cwd, changeJsonPath) {
+    const existing = await readChangeJson(changeJsonPath);
+    const ref = typeof existing.snapshot === "string" && existing.snapshot ? existing.snapshot : null;
+    if (!ref)
+        return null;
+    await pi.exec("git", ["reset", "--hard", ref], { cwd });
+    await pi.exec("git", ["clean", "-fd"], { cwd });
+    await patchChangeJson(changeJsonPath, { snapshot: null, applyState: "aborted" });
+    return ref;
+}
+/** Mark the apply accepted and clear the snapshot. */
+export async function gitAccept(changeJsonPath) {
+    await patchChangeJson(changeJsonPath, { snapshot: null, applyState: "done" });
+}
 function isInside(parent, child) {
     const relative = path.relative(parent, child);
     return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
@@ -198,7 +260,7 @@ function createPiBackend(ctx, maxTokens, onDiagnostic) {
         },
     };
 }
-export async function executeDml(filePath, args, initialMessages, config, pi, ctx, controller, callbacks, runPiAgentStep) {
+export async function executeDml(filePath, args, initialMessages, config, pi, ctx, controller, callbacks, runPiAgentStep, verifyCommands = [], applyChangeJsonPath) {
     const model = ctx.model;
     if (!model)
         throw new Error("Select a pi model before running DeepClause");
@@ -242,9 +304,60 @@ export async function executeDml(filePath, args, initialMessages, config, pi, ct
             },
         });
     }
+    if (verifyCommands.length > 0) {
+        sdk.registerTool(DC_VERIFY_RUN_TOOL, {
+            description: "Run one of the change's pre-approved verification commands in the workspace and return its exit code, stdout and stderr.",
+            parameters: {
+                type: "object",
+                properties: {
+                    command: { type: "string", description: "Exact approved command string" },
+                },
+                required: ["command"],
+            },
+            execute: async (args) => {
+                const command = typeof args.command === "string" ? args.command.trim() : "";
+                if (!verifyCommands.includes(command)) {
+                    throw new Error(`verification command was not approved for this run: ${command}`);
+                }
+                const result = await pi.exec("bash", ["-lc", command], {
+                    cwd: ctx.cwd,
+                    signal: controller.signal,
+                    timeout: 120_000,
+                });
+                return { command, stdout: result.stdout, stderr: result.stderr, exitCode: result.code, killed: result.killed };
+            },
+        });
+    }
+    if (applyChangeJsonPath) {
+        const changeJsonPath = applyChangeJsonPath;
+        sdk.registerTool(DC_APPLY_SNAPSHOT_TOOL, {
+            description: "Record a git snapshot of the workspace before applying tasks. Refuses a dirty working tree.",
+            parameters: { type: "object", properties: {}, required: [] },
+            execute: async () => gitSnapshot(pi, ctx.cwd, changeJsonPath),
+        });
+        sdk.registerTool(DC_APPLY_ACCEPT_TOOL, {
+            description: "Accept the apply so the working tree is not restored.",
+            parameters: { type: "object", properties: {}, required: [] },
+            execute: async () => {
+                await gitAccept(changeJsonPath);
+                return "accepted";
+            },
+        });
+        sdk.registerTool(DC_APPLY_RESTORE_TOOL, {
+            description: "Restore the recorded snapshot, discarding task changes.",
+            parameters: { type: "object", properties: {}, required: [] },
+            execute: async () => (await gitRestore(pi, ctx.cwd, changeJsonPath)) ?? "none",
+        });
+    }
     sdk.setToolPolicy({
         mode: "whitelist",
-        tools: [PI_WORKSPACE_LIST_TOOL, PI_BASH_TOOL, ...(runPiAgentStep ? [PI_AGENT_STEP_TOOL] : [])],
+        tools: [
+            PI_WORKSPACE_LIST_TOOL,
+            PI_BASH_TOOL,
+            ...(runPiAgentStep ? [PI_AGENT_STEP_TOOL] : []),
+            ...(verifyCommands.length > 0 ? [DC_VERIFY_RUN_TOOL] : []),
+            ...(applyChangeJsonPath ? [DC_APPLY_SNAPSHOT_TOOL, DC_APPLY_ACCEPT_TOOL, DC_APPLY_RESTORE_TOOL] : []),
+        ],
     });
     const result = {
         errors: [],

package/dist/workspace.d.ts

@@ -2,6 +2,9 @@ export interface DeepClausePaths {
     root: string;
     skills: string;
     plans: string;
+    specs: string;
+    changes: string;
+    lib: string;
     config: string;
     agents: string;
     reference: string;

package/dist/workspace.js

@@ -46,6 +46,9 @@ export function getPaths(cwd) {
         root,
         skills: path.join(root, "skills"),
         plans: path.join(root, "plans"),
+        specs: path.join(root, "specs"),
+        changes: path.join(root, "changes"),
+        lib: path.join(root, "lib"),
         config: path.join(root, "config.json"),
         agents: path.join(root, "AGENTS.md"),
         reference: path.join(root, "DML_REFERENCE.md"),
@@ -68,6 +71,9 @@ async function bundledReference() {
 async function bundledAuthoringGuide() {
     return readFile(fileURLToPath(new URL("./assets/AGENTS.md", import.meta.url)), "utf8");
 }
+async function bundledAsset(name) {
+    return readFile(fileURLToPath(new URL(`./assets/${name}`, import.meta.url)), "utf8");
+}
 async function bundledDeepResearch() {
     return readFile(fileURLToPath(new URL("./assets/deep_research.dml", import.meta.url)), "utf8");
 }
@@ -76,6 +82,9 @@ export async function initializeWorkspace(cwd) {
     await Promise.all([
         mkdir(paths.skills, { recursive: true }),
         mkdir(paths.plans, { recursive: true }),
+        mkdir(paths.specs, { recursive: true }),
+        mkdir(paths.changes, { recursive: true }),
+        mkdir(paths.lib, { recursive: true }),
     ]);
     await Promise.all([
         writeIfMissing(paths.config, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`),
@@ -83,6 +92,17 @@ export async function initializeWorkspace(cwd) {
         writeIfMissing(paths.reference, await bundledReference()),
         writeIfMissing(path.join(paths.skills, "example.dml"), EXAMPLE_DML),
         writeIfMissing(path.join(paths.skills, "deep_research.dml"), await bundledDeepResearch()),
+        writeIfMissing(path.join(paths.lib, "specs.dml"), await bundledAsset("specs.dml")),
+        writeIfMissing(path.join(paths.lib, "apply.dml"), await bundledAsset("apply.dml")),
+        writeIfMissing(path.join(paths.skills, "spec_validate.dml"), await bundledAsset("spec_validate.dml")),
+        writeIfMissing(path.join(paths.skills, "spec_status.dml"), await bundledAsset("spec_status.dml")),
+        writeIfMissing(path.join(paths.skills, "spec_query.dml"), await bundledAsset("spec_query.dml")),
+        writeIfMissing(path.join(paths.skills, "spec_graph.dml"), await bundledAsset("spec_graph.dml")),
+        writeIfMissing(path.join(paths.skills, "spec_merge.dml"), await bundledAsset("spec_merge.dml")),
+        writeIfMissing(path.join(paths.skills, "spec_archive.dml"), await bundledAsset("spec_archive.dml")),
+        writeIfMissing(path.join(paths.skills, "spec_coverage.dml"), await bundledAsset("spec_coverage.dml")),
+        writeIfMissing(path.join(paths.skills, "spec_scaffold.dml"), await bundledAsset("spec_scaffold.dml")),
+        writeIfMissing(path.join(paths.skills, "spec_apply.dml"), await bundledAsset("spec_apply.dml")),
     ]);
     return paths;
 }

package/docs/DIAGRAM_INTEGRATION_PROPOSAL.md

@@ -0,0 +1,154 @@
+# DML diagrams in `deepclause-pi` — minimal design
+
+## Goal
+
+> The user asks pi to turn a DML file into a diagram — **presentation grade** or
+> **specification grade**. When it's done, a viewer opens.
+
+That's the whole feature. No command suite, no manual build/edit/check/clean
+ritual. Pi does the work; the user just asks.
+
+## How the user experiences it
+
+```text
+User:  “Make me a presentation-grade diagram of
+        skills/deep_research.dml”
+
+pi:    (calls the dc_diagram tool)
+       Creating a presentation-grade diagram for deep_research.dml…
+       (viewer opens in the browser at the Presentation view)
+
+User:  “Now a specification-grade one for the same file”
+
+pi:    (calls dc_diagram with grade=specification)
+       (viewer opens at the Specification view)
+```
+
+The DML file can live **anywhere** — a relative path, an absolute path, or a
+path outside `.pi/deepclause/`. Pi points at it; the tool reads it.
+
+Grade is inferred from the request, or passed explicitly:
+`presentation` / `presentation-grade` → Presentation; `specification` /
+`spec` / `detailed` / `technical` → Specification. If the user says "both",
+produce both views.
+
+## What the extension exposes
+
+Exactly **one model-callable tool**:
+
+```text
+dc_diagram
+  dml   : string                      // path to any .dml file (relative or absolute)
+  grade : "presentation" | "specification" | "both"   // default: presentation
+  view  : "flow" | "sequence"         // optional, default: flow
+```
+
+- Registered on startup (it is a safe, read-and-generate operation — it does not
+  execute the DML, unlike `dc_run`, so it does not need the `/dc-tool` opt-in).
+- `promptGuidelines` tell pi to call it whenever the user asks for a diagram /
+  flowchart / visual of a DML file, to infer the grade from the wording, and not
+  to hand-write Mermaid itself.
+- A short line in `AUTHORING_INSTRUCTION` / `.pi/deepclause/AGENTS.md` mentions
+  the tool and where diagrams live.
+
+Optional, only if we want manual triggering: a single `/dc-diagram <path>
+[--grade=...]` command that does exactly the same thing. Not required.
+
+## What the tool does (one call, end to end)
+
+1. Resolve the input path: relative to the workspace or absolute; require an
+   existing `.dml` file (`realpath` + extension check). No `.pi/deepclause/`
+   restriction on input.
+2. Read the DML and compute a deterministic Mermaid **seed** in-process
+   (`renderDml` / `renderSequence`, ported from `dml_flow.mjs`). Always valid.
+3. If a grade is requested, ask the active pi model to rewrite the seed in that
+   grade (reusing pi's model backend — no `pi_bash`, no API keys), then validate
+   and retry up to ~3 rounds:
+   - **Presentation**: ~8–12 nodes, plain language, headline numbers, 1–2
+     callouts, no function names or framework jargon.
+   - **Specification**: keep function names, `task`/`tool` roles,
+     post-conditions, seed data; precise for an engineer.
+   - Validation: structural checks always; real Mermaid parser via headless
+     Chrome only if Chrome is available. A broken result never reaches the
+     viewer.
+4. Write the sidecar(s) under the active workspace's
+   `.pi/deepclause/diagrams/`: `<name>.presentation.mmd` and/or
+   `<name>.specification.mmd`.
+5. (Re)build `viewer.html` (embedded manifest + vendored Mermaid).
+6. **Open the viewer** at that diagram and view:
+   `xdg-open .pi/deepclause/diagrams/viewer.html?view=presentation#<name>`
+   (fixed argv via `pi.exec`, TUI/interactive only; otherwise just return the
+   path).
+7. Return a one-line result: file, grade, and viewer path.
+
+Progress and cancellation reuse the existing `/dc-run` UI plumbing
+(`setWidget`/`setStatus`, a local `AbortController` wired to the active
+execution so `/dc-cancel` still works).
+
+## Names and collisions
+
+The viewer is keyed by the DML **file name** (without `.dml`). If two DML files
+with the same base name are diagrammed, disambiguate with a short path hash
+(e.g. `deep_research-3f9a`) so sidecars and viewer entries never collide. The
+full source path is always shown in the viewer.
+
+## Artifacts
+
+```text
+.pi/deepclause/diagrams/              # in the active workspace, regardless
+├── viewer.html                       # of where the DML source lives
+├── index.json                        # manifest (also handy for tests/scripts)
+├── <name>.md                         # Mermaid fences for editors
+├── <name>.presentation.mmd           # presentation-grade sidecar
+└── <name>.specification.mmd          # specification-grade sidecar
+```
+
+- Created lazily on first use; `initializeWorkspace()` stays untouched.
+- Output always stays under `.pi/deepclause/`; no `.deepclause/`, no `docs/`.
+- Regenerating a grade overwrites only that sidecar (the user asked for it);
+  the other grade and other diagrams are preserved.
+
+## Viewer
+
+Reuse the handbook `viewer.template.html` nearly verbatim, with the sidebar
+list, theme picker, split pane (editable Mermaid + read-only DML), SVG/PNG
+export and hash deep-links. The view dropdown becomes:
+
+`Presentation → Specification → Flow → Sequence`
+
+Fallback order for the default view: Presentation → Specification → Flow.
+
+## Code changes
+
+```text
+src/diagram/extract.ts     # TS port of dml_flow.mjs (renderDml, renderSequence)
+src/diagram/grade.ts       # model rewrite + validation/retry loop
+src/diagram/viewer.ts      # write sidecars, build viewer.html, open browser
+src/assets/viewer.template.html   # adapted; Presentation/Specification labels
+src/assets/vendor/mermaid.min.js  # vendored, written on first build
+src/runtime.ts             # export a small completeWithPiModel() helper
+src/index.ts               # register dc_diagram + authoring note
+```
+
+## Policy
+
+- No compiler, no `.deepclause/`, no DML execution.
+- Input may be any readable `.dml` path; **output** is confined to the active
+  workspace's `.pi/deepclause/diagrams/`.
+- Does not register runtime tools and does not widen `pi_bash`/approval scope.
+- Browser opening uses a fixed command, not a shell string.
+
+## Validation
+
+- Asking pi for a diagram in natural language results in a `dc_diagram` call and
+  an opened viewer.
+- A DML file outside `.pi/deepclause/` (including an absolute path) works.
+- Presentation vs specification wording selects the right grade; "both"
+  produces both.
+- Chrome present → real-parser gate; Chrome absent → structural gate, viewer
+  still opens.
+- Invalid/partial model output is retried and never written as a final sidecar.
+- Missing file / non-`.dml` input is rejected.
+- Same-name DML files do not collide in the viewer.
+- No approval prompts are raised.
+- No files appear outside `.pi/deepclause/diagrams/`.