deepclause-pi 0.2.0 → 0.4.0

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,6 @@ 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 & {
+    judgeBackend?: string;
+}, 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 { createDeepClause, createJevJudgeBackend, createLLMJudgeBackend } 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,17 +260,38 @@ 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");
     const backend = createPiBackend(ctx, config.maxTokens, callbacks.onDiagnostic ?? (() => { }));
+    // Judgment backends. `llm` reuses pi's active model and credentials; `jev`
+    // is opt-in and only registered when enabled and its key is present.
+    const judgeBackends = {
+        llm: createLLMJudgeBackend({ llmBackend: backend, model: model.id }),
+    };
+    const jev = config.judgment.jev;
+    if (jev.enabled) {
+        const apiKey = process.env[jev.apiKeyEnv];
+        if (apiKey) {
+            judgeBackends.jev = createJevJudgeBackend({ apiKey, model: jev.model });
+        }
+        else {
+            callbacks.onDiagnostic?.(`judgment backend 'jev' is enabled but ${jev.apiKeyEnv} is not set; falling back to 'llm'`);
+        }
+    }
+    const requestedJudge = config.judgeBackend ?? config.judgment.default;
+    if (!judgeBackends[requestedJudge]) {
+        throw new Error(`Judgment backend '${requestedJudge}' is not available. Enable it in .pi/deepclause/config.json or use --judge=llm.`);
+    }
     const sdk = await createDeepClause({
         model: model.id,
         maxTokens: config.maxTokens,
         streaming: true,
         debug: config.verbose,
         llmBackend: backend,
+        judgeBackends,
+        defaultJudge: requestedJudge,
     });
     registerPiRuntimeTools(sdk, pi, ctx.cwd, controller.signal, async (command, signal) => {
         if (!ctx.hasUI)
@@ -242,9 +325,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: [],
@@ -258,6 +392,7 @@ export async function executeDml(filePath, args, initialMessages, config, pi, ct
             gasLimit: config.gasLimit,
             signal: controller.signal,
             initialMessages,
+            judgeBackend: config.judgeBackend,
             onUserInput: (prompt) => callbacks.onInput(prompt, controller.signal),
         })) {
             callbacks.onEvent(event);

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;
 }