deepclause-pi 0.2.0 → 0.3.0

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/SPECKIT.md

@@ -0,0 +1,222 @@
+# deepclause-pi speckit
+
+Spec-driven changes for pi, without leaving the session.
+
+`deepclause-pi speckit` adds a lightweight spec layer on top of the [DeepClause](https://github.com/deepclause/deepclause-sdk) runtime in pi:
+
+- **Specs describe behaviour.** Plain Markdown under `.pi/deepclause/specs/` is the source of truth.
+- **A change is a reviewed proposal.** `.pi/deepclause/changes/<slug>/` holds a proposal, delta specs, optional design notes, and an executable task plan.
+- **Only the model touches prose.** Parsing, validation, merging, coverage, verification and rollback are deterministic DML — no model calls.
+- **Nothing lands silently.** Every step that writes or executes is a gated, reviewable command.
+
+```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/
+```
+
+## Requirements
+
+- pi with this extension installed (see the [README](../README.md#install)).
+- Node.js 22+.
+- Git, for apply snapshots and resumable/rollback behaviour. Without it everything still works, but the apply report says `rollback: unavailable`.
+
+## Getting started
+
+### A new project
+
+```sh
+git init
+printf 'node_modules/\ndist/\n' > .gitignore
+git add -A && git commit -m "init"
+```
+
+Then in pi, once, to seed the workspace:
+
+```text
+/dc
+```
+
+Describe the first feature as a change:
+
+```text
+/dc-plan build a URL shortener with slugs and click counts --change=url_shortener
+```
+
+Pi creates:
+
+```text
+.pi/deepclause/changes/url_shortener/
+├── proposal.md                     # why / what / capabilities / impact
+├── specs/shortener/links.spec.md   # ## Purpose + ## ADDED Requirements + scenarios
+├── design.md                       # approach (optional)
+└── tasks.dml                       # one plan_task per step, with checks
+```
+
+Commit the plan, then run it:
+
+```sh
+git add -A && git commit -m "plan: url_shortener"
+```
+
+```text
+/dc-check url_shortener     # grammar, delta, scenario coverage
+/dc-apply url_shortener     # shows the tasks and the exact command set → confirm
+/dc-archive url_shortener   # shows the merge diff → confirm
+```
+
+Archiving creates `specs/shortener/links.spec.md` and moves the change to `changes/archive/`. That is the bootstrap: **conversation → change → applied → spec.**
+
+Every later feature is the same loop, but pi now reads the existing specs first and writes `## MODIFIED Requirements` when it changes behaviour that already exists.
+
+### An existing project
+
+There is no code-scanning onboarding yet. Two practical routes:
+
+1. **Hand-write the first specs.** Create `specs/<capability>.spec.md` for behaviour you care about, then run `/dc-check` to validate it. This is often the fastest way to capture a system you already understand.
+2. **Document as you go.** Use `/dc-plan ... --change=<slug>` for the next real change. Describe the current behaviour you are building on as `## ADDED Requirements` if it is not yet captured, or trust the code and only specify the new behaviour.
+
+Either way, `specs/` grows one reviewed change at a time.
+
+## Command reference
+
+| Command | Effect |
+|---|---|
+| `/dc` | Status: model, paths, context mode, runtime state |
+| `/dc-list` | Skills, plans, specs and changes |
+| `/dc-plan <request> [--name=slug]` | Standalone executable plan under `plans/` |
+| `/dc-plan <request> --change=<slug>` | Change plan: proposal + delta specs + `tasks.dml` |
+| `/dc-plan update --change=<slug> <request>` | Regenerate a change plan (`tasks.dml` statuses reset to pending) |
+| `/dc-check` | Validate every spec, delta and coverage hole (0 tokens) |
+| `/dc-apply <change>` | Execute tasks; verify, retry, resume |
+| `/dc-apply <change> --abort` | Discard an interrupted apply and restore the snapshot |
+| `/dc-archive <change>` | Merge the delta into `specs/` and move the change to `archive/` |
+| `/dc-run <skill> [args]` | Run any DML skill, e.g. `spec_status`, `spec_query ui/theme` |
+| `/dc-cancel` | Cancel the active execution |
+| `/dc-tool enable\|disable\|status` | Control the model-callable `dc_run` tool |
+
+`/dc-run` refuses skills marked `% Mutating: true` (`spec_apply`, `spec_archive`) so that mutating steps always go through the reviewed `/dc-apply` and `/dc-archive` paths.
+
+### Read-only helpers
+
+```text
+/dc-run spec_status                  # capability + delta inventory
+/dc-run spec_query ui/theme          # one capability's requirements and scenarios
+/dc-run spec_coverage url_shortener  # uncovered scenarios, tasks without checks
+/dc-run spec_merge url_shortener     # merge preview
+/dc-run spec_scaffold url_shortener  # draft tasks.dml text
+/dc-run spec_graph capabilities      # Mermaid graph
+/dc-run spec_graph changes
+```
+
+Ask pi for "the graph of capabilities and changes" and it calls `dc_spec_graph`, which renders the graph in the same offline Mermaid viewer as `dc_diagram`.
+
+## Files
+
+```text
+.pi/deepclause/
+├── specs/<capability>.spec.md          behaviour, source of truth
+├── changes/<slug>/
+│   ├── proposal.md                     why / what / impact
+│   ├── specs/<capability>.spec.md      delta (ADDED / MODIFIED / REMOVED)
+│   ├── design.md                       approach (optional)
+│   ├── tasks.dml                       plan_task/2 + plan_task_status/2
+│   └── change.json                     apply snapshot + applyState
+├── changes/archive/<date>-<slug>/
+├── lib/specs.dml                       parser, validator, merger, coverage
+├── lib/apply.dml                       task driver
+└── skills/spec_*.dml
+```
+
+## Writing specs
+
+A capability spec:
+
+```markdown
+# Theme Specification
+
+## Purpose
+Lets users choose between light and dark themes, defaulting to the OS preference.
+
+## Requirements
+
+### Requirement: Theme selection
+The app SHALL let users switch between light and dark themes at runtime.
+
+#### Scenario: User toggles dark mode
+- **WHEN** the user clicks the theme toggle
+- **THEN** the app switches to dark mode and persists the choice
+```
+
+Rules the validator enforces:
+
+- exactly **three** hashes for `### Requirement:` and **four** for `#### Scenario:` (the classic silent failure);
+- every requirement has at least one scenario;
+- no duplicate requirement names;
+- specs are behaviour only — no commands, file paths, library choices, or task lists.
+
+A delta wraps requirements in `## ADDED Requirements`, `## MODIFIED Requirements`, `## REMOVED Requirements` or `## RENAMED Requirements`:
+
+- `MODIFIED` carries the **full** replacement requirement;
+- `MODIFIED`/`REMOVED` must name a requirement that exists in the target spec (otherwise `/dc-archive` refuses rather than silently dropping it);
+- a brand-new capability may only `ADD`;
+- `RENAMED` is not supported by merge yet — `/dc-archive` refuses it.
+
+Scenario ids are the join key between specs and tasks. They are derived from the scenario name: `Theme selection` in capability `ui/theme` → `ui/theme#theme-selection`. Renaming a scenario changes its id, so `/dc-check` will report the new scenario as uncovered until a task references it.
+
+## The task plan
+
+`tasks.dml` is data, not a program:
+
+```prolog
+plan_task("1.1", task{
+    executor:  pi,
+    do:        "Add a ThemeProvider context exposing theme and setTheme.",
+    tools:     ["read", "edit"],
+    expected:  "src/theme/ThemeProvider.tsx exports ThemeProvider and typechecks.",
+    satisfies: ["ui/theme#theme-selection"],
+    checks:    [ exists("src/theme/ThemeProvider.tsx"),
+                 cmd("npm run typecheck") ]
+}).
+
+% --- execution state (managed by apply.dml; do not edit by hand) ---
+plan_task_status("1.1", pending).
+```
+
+- `executor: pi` delegates a bounded step to pi with exactly the listed tools; `executor: dml` uses contained model reasoning with no pi tools.
+- `satisfies` links the step to delta scenarios; `/dc-check` fails if any delta scenario is uncovered.
+- Checks are declarative: `exists("path")`, `cmd("command")`, `model("question")`.
+- Use `plan_task/2` and `plan_task_status/2` — **not** `task/2`, which collides with DML's built-in `task/N` predicate.
+
+## Verification, resume and rollback
+
+- **Checks** run after each step. A failed check retries the step (up to 3 attempts) with the failure evidence — including command stderr — threaded into the repair instruction.
+- **Verification commands are approved once per run** and then executed through the allowlisted `dc_verify_run` tool. Ordinary `pi_bash` approvals are unaffected.
+- **Snapshots.** `/dc-apply` records a git ref before running and refuses to start on a dirty tree. On success it clears the ref.
+- **Resume.** If a run stops — `/dc-cancel`, a crash, or exhausted retries — the working tree and the `done`/`failed` statuses are **preserved**. Re-run `/dc-apply <change>` and it resumes from the remaining tasks, reusing the original snapshot.
+- **Abort.** `/dc-apply <change> --abort` discards the apply and restores the snapshot (`git reset --hard` + `git clean -fd`), which also resets `tasks.dml` statuses.
+
+A step interrupted halfway is simply re-executed, because its task is not `done` yet and its checks re-verify.
+
+## Committing
+
+After `/dc-plan`, `/dc-apply` and `/dc-archive` leave uncommitted changes, the extension lists the changed files and offers to commit them (`git add -A` with an `<action>: <change>` message), or reminds you when you decline. A clean tree is what lets the next apply take a snapshot.
+
+Suggested `.gitignore`:
+
+```
+.pi/deepclause/diagrams/
+.pi/deepclause/changes/*/change.json
+```
+
+Track `specs/` and `changes/` (including `tasks.dml`); ignore the generated viewer and the transient apply state.
+
+## Limits
+
+- `RENAMED` deltas are validated but not merged yet.
+- There is no digest/drift check between a delta and `specs/` beyond the merge guard; run `/dc-check` after editing specs by hand.
+- `/dc-archive` does not run `/dc-check` for you, and it writes per capability, so run the check first.
+- The `deltas.dml` / `index.dml` derived-fact files from the design are not implemented; queries derive on demand.
+
+See [SPEC_LAYER_PROPOSAL.md](SPEC_LAYER_PROPOSAL.md) for the full design and rationale.