deepclause-pi 0.2.0 → 0.4.0

package/src/planner.ts

@@ -16,6 +16,8 @@ export interface PlanStepSpec {
   requiredTools: string[];
   relevantSkills: string[];
   expectedResult: string;
+  satisfies: string[];
+  checks: string[];
 }
 
 export interface PlanSpec {
@@ -26,6 +28,12 @@ export interface PlanSpec {
   steps: PlanStepSpec[];
   finalSynthesis?: string;
   failureMessage: string;
+  change?: string;
+}
+
+export interface ValidatePlanOptions {
+  requireChecks?: boolean;
+  change?: string;
 }
 
 export interface PlanningSnapshot {
@@ -70,7 +78,12 @@ export function normalizePlanSlug(value: string): string {
   return slug;
 }
 
-export function validatePlanSpec(value: unknown, snapshot: PlanningSnapshot, nameOverride?: string): ValidatedPlan {
+export function validatePlanSpec(
+  value: unknown,
+  snapshot: PlanningSnapshot,
+  nameOverride?: string,
+  options: ValidatePlanOptions = {},
+): ValidatedPlan {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Plan specification must be an object");
   const raw = value as Record<string, unknown>;
   if (!Array.isArray(raw.steps) || raw.steps.length < 1 || raw.steps.length > 12) {
@@ -86,13 +99,19 @@ export function validatePlanSpec(value: unknown, snapshot: PlanningSnapshot, nam
     if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw new Error(`steps[${index}] must be an object`);
     const step = entry as Record<string, unknown>;
     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);
     const executor = step.executor;
     if (executor !== "pi" && executor !== "dml") 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`);
@@ -114,6 +133,8 @@ export function validatePlanSpec(value: unknown, snapshot: PlanningSnapshot, nam
       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)],
     };
   });
 
@@ -127,6 +148,7 @@ export function validatePlanSpec(value: unknown, snapshot: PlanningSnapshot, nam
       ? requireText(raw.finalSynthesis, "finalSynthesis", 2_000)
       : undefined,
     failureMessage: requireText(raw.failureMessage, "failureMessage", 1_000),
+    change: options.change ? normalizePlanSlug(options.change) : undefined,
   };
 
   return {
@@ -148,6 +170,75 @@ function commentText(value: string): string {
   return value.replace(/[\r\n]+/g, " ").replace(/%/g, "percent").trim();
 }
 
+export interface ParsedCheck {
+  kind: "cmd" | "exists" | "model";
+  value: string;
+}
+
+/** Parse an encoded verification check: cmd:<command>, exists:<path>, model:<question>. */
+export function parseCheck(encoded: string): ParsedCheck {
+  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: ValidatedPlan, snapshot: PlanningSnapshot): string {
+  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: DeepClausePaths, slug: string, text: string, overwrite = false): Promise<string> {
+  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 as NodeJS.ErrnoException).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: ValidatedPlan, snapshot: PlanningSnapshot): string {
   const { spec } = plan;
   const resultVariables: string[] = [];
@@ -209,6 +300,16 @@ export async function validateGeneratedPlan(dml: string): Promise<void> {
   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: string): Promise<void> {
+  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: DeepClausePaths, slug: string, dml: string): Promise<string> {
   await mkdir(paths.plans, { recursive: true });
   for (let suffix = 1; suffix <= 100; suffix++) {
@@ -235,7 +336,7 @@ export async function readPlanRequiredTools(filePath: string): Promise<string[]>
   return [...new Set(match[1]!.split(",").map((name) => name.trim()).filter(Boolean))];
 }
 
-export function buildPlanningPrompt(request: string, snapshot: PlanningSnapshot, nameOverride?: string): string {
+export function buildPlanningPrompt(request: string, snapshot: PlanningSnapshot, nameOverride?: string, change?: string, update = false): string {
   const tools = snapshot.allTools.map((tool) => ({
     name: tool.name,
     active: snapshot.activeTools.includes(tool.name),
@@ -244,6 +345,24 @@ export function buildPlanningPrompt(request: string, snapshot: PlanningSnapshot,
     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.",
@@ -253,6 +372,7 @@ export function buildPlanningPrompt(request: string, snapshot: PlanningSnapshot,
     "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/src/runtime.ts

@@ -1,8 +1,9 @@
-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 type {
   DMLEvent,
+  JudgeBackend,
   LLMBackend,
   LLMBackendMessage,
   LLMUsage,
@@ -16,6 +17,66 @@ 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: string): Promise<Record<string, unknown>> {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(changeJsonPath, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+async function patchChangeJson(changeJsonPath: string, patch: Record<string, unknown>): Promise<void> {
+  let existing: Record<string, unknown> = {};
+  try {
+    const parsed: unknown = JSON.parse(await readFile(changeJsonPath, "utf8"));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) existing = parsed as Record<string, unknown>;
+  } 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: Pick<ExtensionAPI, "exec">, cwd: string, changeJsonPath: string): Promise<string> {
+  const existing = await readChangeJson(changeJsonPath);
+  const resumable = typeof existing.snapshot === "string" && existing.snapshot && existing.applyState === "in_progress";
+  if (resumable) return existing.snapshot as string;
+
+  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: Pick<ExtensionAPI, "exec">, cwd: string, changeJsonPath: string): Promise<string | null> {
+  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: string): Promise<void> {
+  await patchChangeJson(changeJsonPath, { snapshot: null, applyState: "done" });
+}
 
 export type BashApproval = (command: string, signal: AbortSignal) => Promise<boolean>;
 
@@ -267,22 +328,50 @@ export async function executeDml(
   filePath: string,
   args: string[],
   initialMessages: MemoryMessage[],
-  config: DeepClauseConfig,
+  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> {
   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: Record<string, JudgeBackend> = {
+    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,
@@ -325,9 +414,62 @@ export async function executeDml(
       },
     });
   }
+  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: ExecutionResult = {
@@ -343,6 +485,7 @@ export async function executeDml(
       gasLimit: config.gasLimit,
       signal: controller.signal,
       initialMessages,
+      judgeBackend: config.judgeBackend,
       onUserInput: (prompt) => callbacks.onInput(prompt, controller.signal),
     })) {
       callbacks.onEvent(event);

package/src/workspace.ts

@@ -7,6 +7,9 @@ export interface DeepClausePaths {
   root: string;
   skills: string;
   plans: string;
+  specs: string;
+  changes: string;
+  lib: string;
   config: string;
   agents: string;
   reference: string;
@@ -57,6 +60,9 @@ export function getPaths(cwd: string): DeepClausePaths {
     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"),
@@ -81,6 +87,10 @@ async function bundledAuthoringGuide(): Promise<string> {
   return readFile(fileURLToPath(new URL("./assets/AGENTS.md", import.meta.url)), "utf8");
 }
 
+async function bundledAsset(name: string): Promise<string> {
+  return readFile(fileURLToPath(new URL(`./assets/${name}`, import.meta.url)), "utf8");
+}
+
 async function bundledDeepResearch(): Promise<string> {
   return readFile(fileURLToPath(new URL("./assets/deep_research.dml", import.meta.url)), "utf8");
 }
@@ -90,6 +100,9 @@ export async function initializeWorkspace(cwd: string): Promise<DeepClausePaths>
   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`),
@@ -97,6 +110,17 @@ export async function initializeWorkspace(cwd: string): Promise<DeepClausePaths>
     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;
 }