deepclause-pi 0.4.0 → 0.5.0

package/dist/index.js

@@ -275,6 +275,18 @@ function viewerVendorAssetPath() {
 function publishResult(pi, content, details) {
     pi.sendMessage({ customType: "deepclause-result", content, display: true, details });
 }
+/**
+ * Ask the user a DeepClause question.
+ *
+ * Pi's interactive text-input dialog renders only its title: the placeholder
+ * argument is ignored by `ExtensionInputComponent`. Passing the question as the
+ * placeholder (as the extension used to) made it invisible, so put the whole
+ * question in the title and label which run is asking.
+ */
+export function requestDeepClauseInput(ctx, label, prompt, signal) {
+    const heading = label ? `DeepClause input — ${label}` : "DeepClause input";
+    return ctx.ui.input(`${heading}\n\n${prompt}`, undefined, { signal });
+}
 export default function deepClauseExtension(pi) {
     let activeController;
     let activeDescription;
@@ -284,6 +296,26 @@ export default function deepClauseExtension(pi) {
     let planCommitRegistered = false;
     let planningTransaction;
     let pendingAgentStep;
+    /**
+     * Claim the single DeepClause execution slot synchronously, before any await.
+     * Without this, parallel `dc_run` calls all pass the `activeController` check
+     * while the first one is still awaiting its setup, then run concurrently and
+     * fight over the one-slot pi input dialog (leaving earlier runs hung).
+     */
+    const claimExecution = (description) => {
+        if (activeController)
+            return undefined;
+        const controller = new AbortController();
+        activeController = controller;
+        activeDescription = description;
+        return controller;
+    };
+    const releaseExecution = (controller) => {
+        if (activeController === controller) {
+            activeController = undefined;
+            activeDescription = undefined;
+        }
+    };
     const setPlanCommitActive = (enabled) => {
         if (enabled && !planCommitRegistered) {
             pi.registerTool({
@@ -479,6 +511,7 @@ export default function deepClauseExtension(pi) {
                 promptGuidelines: [
                     "Use dc_run only for existing DML programs when their deterministic logic, constraints, or specialized orchestration is useful; do not use dc_run to compile natural language or create a skill.",
                     "Do not call dc_run while another DeepClause execution is active, and do not claim success unless dc_run returns an answer without errors.",
+                    "If dc_run reports execution_already_active, wait for the active run to finish and then retry this skill instead of reporting failure.",
                 ],
                 parameters: Type.Object({
                     skill: Type.String({ description: "Skill name such as example, or a DML path relative to .pi/deepclause/." }),
@@ -488,41 +521,40 @@ export default function deepClauseExtension(pi) {
                     })),
                 }),
                 async execute(_toolCallId, params, signal, onUpdate, ctx) {
-                    if (activeController) {
+                    const controller = claimExecution("dc_run");
+                    if (!controller) {
                         return {
-                            content: [{ type: "text", text: "DeepClause execution rejected: another execution is already active." }],
+                            content: [{ type: "text", text: "DeepClause execution rejected: another execution is active. Wait for it to finish, then call dc_run again for this skill." }],
                             details: { success: false, error: "execution_already_active" },
                         };
                     }
-                    const paths = await initializeWorkspace(ctx.cwd);
-                    const config = await loadConfig(paths.config);
-                    if (!config.modelToolEnabled || !pi.getActiveTools().includes(DC_RUN_TOOL)) {
-                        return {
-                            content: [{ type: "text", text: "The dc_run tool is disabled. The user can enable it with /dc-tool enable." }],
-                            details: { success: false, error: "tool_disabled" },
-                        };
-                    }
-                    const mode = params.context ?? config.contextMode;
-                    const filePath = await resolveDmlPath(paths, params.skill);
-                    if (await isContextualPlan(filePath)) {
-                        return {
-                            content: [{ type: "text", text: "Contextual DML plans must be started by the user with /dc-run; they cannot start a nested pi agent turn from dc_run." }],
-                            details: { success: false, error: "interactive_plan_requires_user_run" },
-                        };
-                    }
-                    const skillName = path.relative(paths.root, filePath);
-                    const initialMessages = buildInitialMessages(ctx.sessionManager.getBranch(), mode, config.branchMessageLimit);
-                    const controller = new AbortController();
                     const cancel = () => controller.abort(signal?.reason ?? new Error("dc_run cancelled"));
                     if (signal?.aborted)
                         cancel();
                     else
                         signal?.addEventListener("abort", cancel, { once: true });
-                    activeController = controller;
-                    activeDescription = `model tool running ${skillName}`;
-                    const startedAt = Date.now();
-                    const progress = [];
                     try {
+                        const paths = await initializeWorkspace(ctx.cwd);
+                        const config = await loadConfig(paths.config);
+                        if (!config.modelToolEnabled || !pi.getActiveTools().includes(DC_RUN_TOOL)) {
+                            return {
+                                content: [{ type: "text", text: "The dc_run tool is disabled. The user can enable it with /dc-tool enable." }],
+                                details: { success: false, error: "tool_disabled" },
+                            };
+                        }
+                        const mode = params.context ?? config.contextMode;
+                        const filePath = await resolveDmlPath(paths, params.skill);
+                        if (await isContextualPlan(filePath)) {
+                            return {
+                                content: [{ type: "text", text: "Contextual DML plans must be started by the user with /dc-run; they cannot start a nested pi agent turn from dc_run." }],
+                                details: { success: false, error: "interactive_plan_requires_user_run" },
+                            };
+                        }
+                        const skillName = path.relative(paths.root, filePath);
+                        activeDescription = `model tool running ${skillName}`;
+                        const initialMessages = buildInitialMessages(ctx.sessionManager.getBranch(), mode, config.branchMessageLimit);
+                        const startedAt = Date.now();
+                        const progress = [];
                         const result = await executeDml(filePath, params.args ?? [], initialMessages, config, pi, ctx, controller, {
                             onEvent: (event) => {
                                 if (event.type === "output" && event.content)
@@ -544,7 +576,7 @@ export default function deepClauseExtension(pi) {
                             onInput: async (prompt, inputSignal) => {
                                 if (!ctx.hasUI)
                                     throw new Error("dc_run cannot request user input without interactive UI");
-                                const answer = await ctx.ui.input("DeepClause input", prompt, { signal: inputSignal });
+                                const answer = await requestDeepClauseInput(ctx, skillName, prompt, inputSignal);
                                 if (answer === undefined)
                                     throw new Error("Input cancelled");
                                 return answer;
@@ -571,13 +603,12 @@ export default function deepClauseExtension(pi) {
                         const message = error instanceof Error ? error.message : String(error);
                         return {
                             content: [{ type: "text", text: `DeepClause execution failed: ${message}` }],
-                            details: { success: false, skill: skillName, contextMode: mode, error: message },
+                            details: { success: false, error: message },
                         };
                     }
                     finally {
                         signal?.removeEventListener("abort", cancel);
-                        activeController = undefined;
-                        activeDescription = undefined;
+                        releaseExecution(controller);
                     }
                 },
             });
@@ -596,11 +627,11 @@ export default function deepClauseExtension(pi) {
             pi.registerTool({
                 name: DC_DIAGRAM_TOOL,
                 label: "Create DeepClause Diagram",
-                description: "Create a presentation-grade or specification-grade Mermaid diagram from any .dml file, write a self-contained offline viewer under .pi/deepclause/diagrams/, and open it.",
+                description: "Create a presentation-grade or specification-grade Mermaid diagram from any .dml file, write a self-contained offline viewer under .pi/deepclause/diagrams/, and open it. The specification grade preserves the core decision logic and rule facts.",
                 promptSnippet: "Create a presentation- or specification-grade diagram from a DML file",
                 promptGuidelines: [
                     "Use dc_diagram whenever the user asks for a diagram, flowchart, or visual of a .dml file; pass the exact path the user named.",
-                    "Choose grade=presentation for slides and overviews and grade=specification for engineering detail; use grade=both only when the user asks for both.",
+                    "Choose grade=presentation for slides and overviews and grade=specification for engineering detail (decision predicates, thresholds, rule facts); use grade=both only when the user asks for both.",
                     "Do not hand-write Mermaid or run diagram tools yourself; call dc_diagram and report the viewer result.",
                 ],
                 parameters: Type.Object({
@@ -609,52 +640,47 @@ export default function deepClauseExtension(pi) {
                     view: Type.Optional(StringEnum(["flow", "sequence"], { description: "Base layout used to seed the grade; default flow." })),
                 }),
                 async execute(_toolCallId, params, signal, onUpdate, ctx) {
-                    if (activeController) {
+                    const controller = claimExecution("dc_diagram");
+                    if (!controller) {
                         return {
                             content: [{ type: "text", text: "Another DeepClause operation is already active; wait for it to finish." }],
                             details: { success: false, error: "execution_already_active" },
                         };
                     }
-                    const requested = resolveGrade(String(params.grade ?? "")) ?? "presentation";
-                    const grades = requested === "both" ? ["presentation", "specification"] : [requested];
-                    const view = params.view === "sequence" ? "sequence" : "flow";
-                    let sourcePath;
-                    try {
-                        sourcePath = await resolveDiagramSource(ctx.cwd, params.dml);
-                    }
-                    catch (error) {
-                        const message = error instanceof Error ? error.message : String(error);
-                        return { content: [{ type: "text", text: `dc_diagram failed: ${message}` }], details: { success: false, error: message } };
-                    }
-                    if (!ctx.model) {
-                        return {
-                            content: [{ type: "text", text: "dc_diagram requires an active pi model. Select one and try again." }],
-                            details: { success: false, error: "no_model" },
-                        };
-                    }
-                    const config = await loadConfig(getPaths(ctx.cwd).config);
-                    const source = await readFile(sourcePath, "utf8");
-                    const display = displayPath(ctx.cwd, sourcePath);
-                    const seed = view === "sequence"
-                        ? renderSequence(display, source)
-                        : renderDml(display, source, { hideOutput: true });
-                    const targets = await collectDiagramTargets(ctx.cwd, [sourcePath]);
-                    const name = diagramNameFor(sourcePath, targets, ctx.cwd);
-                    const { diagrams, vendor } = await ensureDiagramDir(ctx.cwd, viewerVendorAssetPath());
-                    const templateText = await bundledViewerTemplate();
-                    const controller = new AbortController();
                     const cancel = () => controller.abort(signal?.reason ?? new Error("dc_diagram cancelled"));
                     if (signal?.aborted)
                         cancel();
                     else
                         signal?.addEventListener("abort", cancel, { once: true });
-                    activeController = controller;
-                    activeDescription = `diagram ${name} (${grades.join("+")})`;
-                    const run = (command, args, options) => pi.exec(command, args, options);
-                    let chrome;
-                    let chromeResolved = false;
                     try {
+                        const requested = resolveGrade(String(params.grade ?? "")) ?? "presentation";
+                        const grades = requested === "both" ? ["presentation", "specification"] : [requested];
+                        const view = params.view === "sequence" ? "sequence" : "flow";
+                        const sourcePath = await resolveDiagramSource(ctx.cwd, params.dml);
+                        if (!ctx.model) {
+                            return {
+                                content: [{ type: "text", text: "dc_diagram requires an active pi model. Select one and try again." }],
+                                details: { success: false, error: "no_model" },
+                            };
+                        }
+                        const config = await loadConfig(getPaths(ctx.cwd).config);
+                        const source = await readFile(sourcePath, "utf8");
+                        const display = displayPath(ctx.cwd, sourcePath);
+                        const targets = await collectDiagramTargets(ctx.cwd, [sourcePath]);
+                        const name = diagramNameFor(sourcePath, targets, ctx.cwd);
+                        const { diagrams, vendor } = await ensureDiagramDir(ctx.cwd, viewerVendorAssetPath());
+                        const templateText = await bundledViewerTemplate();
+                        activeDescription = `diagram ${name} (${grades.join("+")})`;
+                        const run = (command, args, options) => pi.exec(command, args, options);
+                        let chrome;
+                        let chromeResolved = false;
                         for (const grade of grades) {
+                            // The specification seed carries the core decision logic and rule
+                            // facts; the presentation seed stays small so the model can keep
+                            // it to a general-audience overview.
+                            const seed = view === "sequence"
+                                ? renderSequence(display, source)
+                                : renderDml(display, source, { hideOutput: true, includeLogic: grade === "specification" });
                             const result = await polishDiagram({
                                 grade,
                                 view,
@@ -700,8 +726,7 @@ export default function deepClauseExtension(pi) {
                     }
                     finally {
                         signal?.removeEventListener("abort", cancel);
-                        activeController = undefined;
-                        activeDescription = undefined;
+                        releaseExecution(controller);
                     }
                 },
             });
@@ -768,13 +793,13 @@ export default function deepClauseExtension(pi) {
         }
     };
     const runSpecSkill = async (ctx, skill, args = [], options = {}) => {
-        const paths = await initializeWorkspace(ctx.cwd);
-        const config = await loadConfig(paths.config);
-        const filePath = await resolveDmlPath(paths, skill);
-        const controller = new AbortController();
-        activeController = controller;
-        activeDescription = `running ${skill}`;
+        const controller = claimExecution(`running ${skill}`);
+        if (!controller)
+            throw new Error("Another DeepClause execution is already active");
         try {
+            const paths = await initializeWorkspace(ctx.cwd);
+            const config = await loadConfig(paths.config);
+            const filePath = await resolveDmlPath(paths, skill);
             const result = await executeDml(filePath, args, [], config, pi, ctx, controller, {
                 onEvent() { },
                 onInput: async () => { throw new Error("spec skills do not request input"); },
@@ -784,8 +809,7 @@ export default function deepClauseExtension(pi) {
             return result.answer ?? "(no answer)";
         }
         finally {
-            activeController = undefined;
-            activeDescription = undefined;
+            releaseExecution(controller);
         }
     };
     pi.on("session_start", async (_event, ctx) => {
@@ -1194,7 +1218,8 @@ export default function deepClauseExtension(pi) {
     pi.registerCommand("dc-run", {
         description: "Run a DML skill with pi's active model",
         handler: async (rawArgs, ctx) => {
-            if (activeController) {
+            const controller = claimExecution("dc-run");
+            if (!controller) {
                 ctx.ui.notify("A DeepClause execution is already active", "warning");
                 return;
             }
@@ -1229,8 +1254,6 @@ export default function deepClauseExtension(pi) {
                 }
                 const mode = parsed.contextMode ?? config.contextMode;
                 const initialMessages = buildInitialMessages(ctx.sessionManager.getBranch(), mode, config.branchMessageLimit);
-                const controller = new AbortController();
-                activeController = controller;
                 const outputLines = [];
                 const recentEvents = [];
                 const events = [];
@@ -1309,7 +1332,7 @@ export default function deepClauseExtension(pi) {
                         onEvent,
                         onDiagnostic,
                         onInput: async (prompt, signal) => {
-                            const answer = await ctx.ui.input("DeepClause input", prompt, { signal });
+                            const answer = await requestDeepClauseInput(ctx, skillName, prompt, signal);
                             if (answer === undefined)
                                 throw new Error("Input cancelled");
                             return answer;
@@ -1340,8 +1363,7 @@ export default function deepClauseExtension(pi) {
                 ctx.ui.notify(message, activeController?.signal.aborted ? "warning" : "error");
             }
             finally {
-                activeController = undefined;
-                activeDescription = undefined;
+                releaseExecution(controller);
                 ctx.ui.setStatus(STATUS_KEY, undefined);
                 ctx.ui.setWidget(WIDGET_KEY, undefined);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepclause-pi",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Pi-hosted runtime for DeepClause DML programs",
   "type": "module",
   "license": "MIT",

package/skills/handbook-dml/SKILL.md

@@ -1,14 +1,16 @@
 ---
 name: handbook-dml
-description: Convert a long handbook/SOP into one DeepClause DML skill per workflow — an LLM-first subagent (agentic task/N leaves, narrow tool/2 capabilities) that takes a generic natural-language request as input and uses deterministic Prolog only for mechanical checks, with LLM fallback. Also teaches a tool audit, user confirmation, and how to write the repo-root AGENTS.md policy-routing table so pi calls the skills automatically via dc_run. Use when asked to turn a handbook or procedures manual into executable DML, update a handbook-derived skill, or wire the policy router.
+description: Convert a long handbook/SOP into one DeepClause DML skill per workflow — a `task/N` subagent for agentic work, the judgment predicates (`choose`/`rate`/`verify`/`probability`/`holds`/`judge`) for bounded classification and calibrated gates, and deterministic Prolog only for mechanical checks, always with fallbacks. Also teaches a tool audit, user confirmation, and how to write the repo-root AGENTS.md policy-routing table so pi calls the skills automatically via dc_run. Use when asked to turn a handbook or procedures manual into executable DML, update a handbook-derived skill, choose between a classifier, a probability gate, and a full agent task, or wire the policy router.
 ---
 
 # Handbook → DML (procedures)
 
-Turn a long handbook into **one DML skill per workflow/procedure**. Each skill is
-an **LLM-first subagent**: agentic `task/N` leaves do the reading, reasoning,
-and acting, while Prolog handles only what is genuinely mechanical (arithmetic,
-counting, exact equality) or a hard safety invariant.
+Turn a long handbook into **one DML skill per workflow/procedure**. Each skill
+combines three primitives: agentic `task/N` leaves for work that must act or
+reason across turns, bounded judgment predicates (`choose`/`rate`/`verify`/
+`probability`/`holds`) for classification and calibrated gates, and Prolog only
+for what is genuinely mechanical (arithmetic, counting, exact equality) or a
+hard safety invariant.
 
 Before writing DML, read `.pi/deepclause/AGENTS.md` and
 `.pi/deepclause/DML_REFERENCE.md`. They are authoritative for syntax.
@@ -17,19 +19,117 @@ Before writing DML, read `.pi/deepclause/AGENTS.md` and
 
 - **Pi authors; DML is the runtime artifact.** Decomposition and authoring happen
   in a normal pi turn. There is no Markdown→DML compiler.
-- **LLM-first.** Rules and flow are `task/N` / `prompt/N` by default. Use Prolog
-  only where a rule is mechanical or must never be wrong.
+- **Pick the cheapest primitive.** Bounded classifications, ratings, yes/no
+  checks, and probabilities use the judgment predicates (`choose/4`, `rate/4`,
+  `verify/3`, `probability/3`, `holds/2-3`, `judge/2`). Fresh-context generation
+  and critique use `prompt/N`. Multi-turn work with memory, tools, and typed
+  outputs uses `task/N`. Use Prolog only where a rule is mechanical or must
+  never be wrong. See **Choosing the reasoning primitive** below.
 - **Input is a generic request.** `agent_main(Request)` takes free text; the
   first step is an LLM `task/N` that parses it into a typed `object/1` case (or
   the request is used directly for simple skills).
 - **Forbidden actions become tool scoping.** "Never send" means *no send tool*.
   "Read-only inspection" means the inspect phase gets read tools only.
-- **Every deterministic rule gets an LLM fallback.** If a deterministic check
-  fails, branch to a `prompt/N`/`task/N` that reviews, repairs, or asks the user
-  — do not hard-fail.
+- **Every deterministic rule gets a fallback.** If a deterministic check
+  fails, branch to a judgment, a `prompt/N`/`task/N`, or the user — do not
+  hard-fail.
 - **Ask, don't assume.** Confirm scope, the decomposition, and tool choices with
   the user before authoring.
 
+## Choosing the reasoning primitive
+
+Before writing flow, ask what the **core question** of each step is. A full
+`task/N` agent loop carries memory, DML tools, and a multi-turn reasoning loop;
+it is the right answer only when the step must act or reason iteratively. A
+bounded question over explicit text should use the judgment predicates instead:
+they are cheaper, the answer is constrained to the labels/levels you supply,
+they never touch DML memory, and they cannot call tools.
+
+| Core question | Primitive | Notes |
+| --- | --- | --- |
+| "Which category/team/route?" from a small closed set | `choose/4` (or `judge/2` with `choose`) | The answer is always one of your option atoms |
+| "How severe/frustrated/confident?" (ordered) | `rate/4` | Answer is constrained to your levels |
+| "Is X true?" / "Does it ask for a refund?" | `verify/3`, or `holds/2` when only the boolean matters | Three-valued: `yes` / `no` / `unknown` |
+| "How likely is X?" / "Is it over a threshold?" | `probability/3`, or `holds/3` for a threshold gate | Decision-grade only when the backend reports `calibrated` |
+| Free-form generation, rewrite, or critique of supplied text | `prompt/N` | Fresh context, no tools, no memory |
+| Multi-step job needing tools, memory, or iteration | `task/N` | Typed outputs; scope tools with `with_tools/2` |
+
+**Simple classifier.** If the core question reduces to choosing among a fixed
+set of labels, use `choose/4`. Do not spend a `task/N` on it, and do not let the
+model invent a label: the judge is constrained to your options.
+
+```prolog
+route(Request, Team) :-
+    choose(Request, "Which team should handle this request?",
+           [billing-"Charges and refunds", orders-"Delivery and returns", account-"Login and security"],
+           Team).
+```
+
+**Calibrated probability.** If the decision depends on a probability, say so and
+gate it. The default `llm` backend is *uncalibrated*: a number from it is an
+estimate, not a calibrated probability. Wrap the judgment in
+`require_judgment(calibrated, ...)` so the skill cannot silently run on a
+backend that only estimates, and provide a fallback clause.
+
+```prolog
+risk_band(Text, Band) :-
+    require_judgment(calibrated,
+        probability(Text, "What is the probability this is high risk?", P)),
+    (   P >= 0.8 -> Band = high
+    ;   P >= 0.4 -> Band = medium
+    ;   Band = low
+    ).
+
+risk_band(Text, Band) :-
+    % Uncalibrated fallback: a coarse classifier, never a fake probability.
+    choose(Text, "Is this high, medium, or low risk?", [high, medium, low], Band).
+```
+
+`holds(Text, Question, Threshold)` is the concise form when you only need the
+threshold decision, and `holds(Text, Question)` is the concise form of a yes/no
+check. `with_judgment(jev, Goal)` pins a scope to a specific backend (for
+example a calibrated one). `require_judgment/2` fails **before** the judgment
+runs, which is what makes the fallback clause above reachable; the runtime emits
+a warning naming the missing capability.
+
+**Full agent loop.** Use `task/N` (or `prompt/N`) when the step needs to read
+accumulated memory, call a DML tool, run several model turns, or produce
+free-form text. The judgment layer deliberately cannot do those things.
+
+**Batch judgments.** When one step needs more than one or two judgments, send a
+single `judge/2` batch rather than several one-offs:
+
+```prolog
+judge(Message, [
+    choose("Which team should handle this?", [billing, orders, account]) - Team,
+    rate("How frustrated is the customer?", [calm, frustrated, angry]) - Frustration,
+    verify("Does the message ask for a refund?") - Refund,
+    probability("Is this urgent?") - Urgency
+]).
+```
+
+### Judgment rules
+
+- `judge/2`, `choose/4`, `rate/4`, `verify/3`, `probability/3`, `holds/2`,
+  `holds/3`, `with_judgment/2`, and `require_judgment/2` are runtime special
+  predicates. Do not define your own predicates with those names — a common
+  collision is a hand-written `verify/3`. Name deterministic helpers
+  `verify_task/3`, `check_*`, and so on.
+- `verify` is three-valued. `\+ verify(...)` does **not** mean "the model said
+  no"; inspect the returned `yes` / `no` / `unknown`.
+- Keep `State` explicit: pass the exact text or object to judge. The judge sees
+  only that state plus the question and never reads DML memory.
+- A `choose`/`rate` answer is constrained to your options/levels, so make them
+  exhaustive and mutually exclusive.
+- Never present an `estimated` probability as `calibrated`. Require the
+  capability and fall back, or label the output as an estimate.
+- Answers are memoized per run by backend, model, state, and questions, so
+  backtracking reuses an answer instead of re-querying the model.
+- The deterministic linter warns when a skill has no `task()` call and suggests
+  `task()` for classification. That heuristic predates the judgment layer: a
+  skill whose core question is a bounded judgment can legitimately have no
+  `task/N`.
+
 ## Workflow
 
 1. **Ingest** the handbook to Markdown (PDF→`pdftotext`, DOCX/HTML→`pandoc`).
@@ -121,6 +221,13 @@ tool(user_feedback(Prompt, Response), "Ask the user one focused question and ret
     exec(ask_user(prompt: Prompt), Result),
     get_dict(user_response, Result, Response).
 
+% --- bounded judgments (cheap: no memory, no tools) ------------------------
+% Prefer a judgment over a task/N for a bounded question about explicit text.
+% classify(Request, Kind) :-
+%     choose(Request, "Which case type is this?", [<kind_a>, <kind_b>, other], Kind).
+% confirm_requirement(Report) :-
+%     holds(Report, "Does the report include the required referral advice?", 0.7).
+
 % --- deterministic helpers (mechanical only) -------------------------------
 <compute_or_check>(...).          % arithmetic/counts; keep small
 
@@ -136,7 +243,7 @@ agent_main(Request) :-
     with_tools([<write tools>], (
         task("Produce the required effects for this case: {ConfirmedCase}.", string(Summary))
     )),
-    <optional verification with LLM fallback>,
+    <optional judgment / prompt / deterministic verification with fallback>,
     answer(Final).
 
 agent_main(_) :-
@@ -146,49 +253,59 @@ agent_main(_) :-
 Notes:
 
 - `task/N` = agentic leaf (memory + DML tools). `prompt/N` = fresh-context
-  review. `with_tools/2` scopes capability per phase.
+  generation/review. `choose`/`rate`/`verify`/`probability` = the judgment layer.
+  `with_tools/2` scopes capability per phase.
+- Prefer a judgment over a `task/N` whenever the core question is a bounded
+  classification, rating, yes/no check, or probability gate.
 - Build `task/N` descriptions with `format/3` (not `{Var}` interpolation) when
   you embed dynamic values — avoids singleton-variable noise.
 - Mutable facts must be declared `:- dynamic` before `assertz`/`retract`.
 
-## Verification (optional, LLM-first)
+## Verification (optional)
+
+Only add checks when the procedure has observable post-conditions. Match the
+check to the question: a bounded semantic check is a judgment, an open-ended
+read is a model review, and a count is deterministic. Every check needs a
+fallback path so it never hard-fails.
 
-Only add checks when the procedure has observable post-conditions. Prefer model
-review; use deterministic checks only for mechanical facts, and always give a
-deterministic check an LLM fallback.
+- **Semantic gate (default for bounded checks).** "Does the output recommend
+  urgent referral when a danger sign is present?" is a `verify/3` question, or
+  `holds/2` when you only need the boolean. Use `holds/3` when the check is a
+  probability threshold.
+- **Model review (`prompt/N`).** Tone, completeness, correctness of free text,
+  "does this read right", and open-ended rubric interpretation.
+- **Deterministic (only when mechanical).** Counts, exact IDs, arithmetic. Keep
+  it tiny, and route failures to a judgment, a review, or the user.
 
 ```prolog
-% deterministic gate (mechanical only)
-holds(drafts_count) :- findall(_, draft(_,_,_,_), Ds), length(Ds, 2).
-
-verify_state(Failed, Report) :-
-    findall(Name, (postcondition(Name), \+ holds(Name)), Failed),
-    ( Failed = [] -> Report = "PASS" ; format(string(Report), "FAIL: ~w", [Failed]) ).
-
-% LLM fallback: never hard-fail on a deterministic check
-fallback_review(Failed, Verdict, Reason) :-
-    format(string(Prompt),
-        "These structural checks failed: ~w. Review the outcome and the requirement. Store 'acceptable' or 'needs-attention' in Verdict and a one-line reason in Reason.",
-        [Failed]),
-    prompt(Prompt, string(Verdict), string(Reason)).
+% Semantic gate: a bounded yes/no question about explicit text.
+referral_ok(Report) :-
+    holds(Report, "Does the report recommend urgent referral when a danger sign is present?").
+
+% Deterministic gate (mechanical only).
+drafts_complete :- findall(_, draft(_,_,_,_), Ds), length(Ds, 2).
+
+verify_state(Report, Note) :-
+    (   referral_ok(Report), drafts_complete
+    ->  Note = "verification passed"
+    ;   % Fallback: never hard-fail; explain the failure and let pi/user decide.
+        format(string(Prompt),
+            "Review this outcome against the requirement and explain any gap: ~w. Store 'acceptable' or 'needs-attention' in Verdict and a one-line reason in Reason.",
+            [Report]),
+        prompt(Prompt, string(Verdict), string(Reason)),
+        format(string(Note), "fallback verdict ~w: ~w", [Verdict, Reason])
+    ).
 ```
 
 In `agent_main`:
 
 ```prolog
-verify_state(Failed, Report),
-(   Failed = [] -> V = "n/a", R = "deterministic checks passed"
-;   fallback_review(Failed, V, R)
-),
-answer(... report Report + V/R ...).
+verify_state(Report, Note),
+answer(... report + Note ...).
 ```
 
-Choosing:
-
-- **Model review** (default): tone, completeness, correctness of free text,
-  "does this read right", and anything the rubric phrases as a judgment.
-- **Deterministic** (only when mechanical): counts, exact IDs, arithmetic. Keep
-  it tiny, and route failures to the model or the user instead of failing.
+For a calibrated postcondition, wrap `holds(Report, Question, Threshold)` in
+`require_judgment(calibrated, ...)` and keep the same fallback pattern.
 
 ## Dummy tools
 
@@ -243,10 +360,13 @@ For each generated skill:
    — runs clean; verification (if any) passes or the fallback explains.
 2. Inspect phase is read-only, action phase is write-only, and a forbidden
    action has no tool at all.
-3. Deterministic code is limited to arithmetic/counts; every deterministic
-   check has an LLM fallback branch.
-4. The tool audit was done and its result is recorded in the header/INDEX.
-5. Re-check the invalid-pattern table in `.pi/deepclause/AGENTS.md` (singleton
+3. Bounded classifications and checks use the judgment predicates; calibrated
+   probabilities are wrapped in `require_judgment(calibrated, ...)` with a
+   fallback clause, and `verify/3` results are read as `yes`/`no`/`unknown`.
+4. Deterministic code is limited to arithmetic/counts; every deterministic
+   check has a model/judgment fallback branch.
+5. The tool audit was done and its result is recorded in the header/INDEX.
+6. Re-check the invalid-pattern table in `.pi/deepclause/AGENTS.md` (singleton
    variables, `~` vs `{}` interpolation, `Result.field` vs `get_dict/3`, `->`
    committing over generators, `answer/1` last, `:- dynamic` before
    `assertz/retract`).
@@ -254,12 +374,20 @@ For each generated skill:
 `--context=isolated` keeps session text out of the run. The runtime still needs
 a model selected.
 
+To exercise calibrated judgments for real, enable the Jev backend
+(`/dc-judge enable`, `/dc-judge default jev`, or `--judge=jev`) and export the
+backend's API key (default `TYPESAFE_API_KEY`) in the shell that launches pi.
+Without it, the `llm` backend is uncalibrated and the
+`require_judgment(calibrated, ...)` branch is skipped in favor of the fallback.
+
 ## Reference shape
 
 A typical procedure skill has: `agent_main(Request)` that parses the request
-with `task/N`, confirms with the user via a `user_feedback` tool loop, acts
+with `task/N`, confirms with the user via a `user_feedback` tool loop, uses
+bounded judgments (`choose`/`verify`/`holds`) for classification and gates, acts
 through write tools, and reviews with `prompt/N` — with small deterministic
 helpers for arithmetic and a fallback branch instead of hard failures.
 
 For DML mechanics, see the bundled example skills in a fresh workspace
-(`example.dml`, `deep_research.dml`) and `.pi/deepclause/AGENTS.md`.
+(`example.dml`, `deep_research.dml`), `.pi/deepclause/DML_REFERENCE.md` (the
+judgment predicates are documented there), and `.pi/deepclause/AGENTS.md`.