deepclause-pi 0.3.0 → 0.5.0

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`.

package/src/assets/AGENTS.md

@@ -111,15 +111,51 @@ A task can bind up to four outputs. Keep each task focused even though the runti
 
 ### `prompt/N`: an isolated model call
 
-Use `prompt/N` for a subtask that should not inherit accumulated conversation memory: independent classification, adversarial review, or formatting based only on explicitly supplied text.
+Use `prompt/N` for a subtask that should not inherit accumulated conversation memory: adversarial review, rewriting, or formatting based only on explicitly supplied text. For a bounded classification, prefer the judgment predicates below.
 
 ```prolog
-prompt("Classify this text as low, medium, or high risk: {Text}. Store the label in Risk.",
-       string(Risk)).
+prompt("Rewrite this summary in plain language for a patient: {Text}. Store only the rewrite in Plain.",
+       string(Plain)).
 ```
 
 Fresh context is not a security boundary. Untrusted text can still contain hostile instructions; delimit it, state how it may be used, and request narrow structured output.
 
+### Semantic judgments: bounded, typed questions
+
+Use the judgment predicates when the core question is a **bounded, typed question about explicit state**. They are not agentic: they do not read or write DML memory, they cannot call tools, and their answers are constrained to the options or levels you supply. That makes them cheaper and more reliable than a `task/N` for classification, rating, verification, and probability gates.
+
+| Core question | Predicate |
+| --- | --- |
+| "Which label/route?" from a closed set | `choose(State, Question, Options, Choice)` |
+| "How severe/frustrated/confident?" on an ordered scale | `rate(State, Question, Levels, Level)` |
+| "Is X true?" (`yes`/`no`/`unknown`) | `verify(State, Question, Truth)`; `holds(State, Question)` for a semidet check |
+| "How likely is X?" / "Is it above a threshold?" | `probability(State, Question, P)`; `holds(State, Question, Threshold)` |
+
+Batch several questions into one request with `judge/2`:
+
+```prolog
+judge(Message, [
+    choose("Which team should handle this?", [billing, orders, account]) - Team,
+    verify("Does the message ask for a refund?") - Refund
+]).
+```
+
+Gate a calibrated probability and fall back when the backend only estimates:
+
+```prolog
+risk_band(Text, Band) :-
+    require_judgment(calibrated, probability(Text, "Risk of harm?", P)),
+    ( P >= 0.8 -> Band = high ; Band = low ).
+risk_band(Text, Band) :-
+    choose(Text, "Is the risk high or low?", [high, low], Band).
+```
+
+`with_judgment(Backend, Goal)` selects a backend per scope; `require_judgment/2` fails before the judgment runs when the backend lacks a capability such as `calibrated`, so the second clause is the fallback. Answers are memoized per run by backend, model, state, and questions, so backtracking is cheap.
+
+Do not name your own predicates `choose/4`, `rate/4`, `verify/3`, `probability/3`, `holds/2`, `holds/3`, `judge/2`, `with_judgment/2`, or `require_judgment/2`; they are runtime special predicates. `verify` is three-valued — never treat `\+ verify(...)` as "the model said no".
+
+See `DML_REFERENCE.md` for the full syntax, options, and capability list.
+
 ### `llm/2`: low-level completion
 
 Prefer `task/N` and `prompt/N`. Use `get_memory/1` plus `llm/2` only when the program intentionally needs a raw completion over an explicit message list and does not need the task loop's result tools or DML tools.
@@ -357,7 +393,7 @@ Represent stable facts and rules as Prolog clauses; expose narrow query/update t
 
 ### 6. Independent reviewers
 
-Use `task/N` to draft and `prompt/N` to review from fresh context, then apply deterministic acceptance criteria. Best for code review, risk assessment, and editorial checks.
+Use `task/N` to draft and `prompt/N` to review from fresh context, then apply deterministic acceptance criteria. Best for code review, risk assessment, and editorial checks. When the review is a bounded checklist ("does it state the referral threshold?"), use `verify/3` or `holds/2` instead of a free-form reviewer.
 
 ### 7. Pure deterministic utility
 
@@ -388,10 +424,10 @@ Pi can turn any DML file into a self-contained, offline Mermaid viewer. Ask for
 
 Pi calls the `dc_diagram` model tool with the DML path and a grade:
 
-- **presentation** — about 8-12 nodes, plain language, headline numbers (slides and overviews).
-- **specification** — function names, task/tool roles, post-conditions (engineers).
+- **presentation** — about 8-12 nodes, plain language, headline numbers and the headline decision (slides and overviews).
+- **specification** — function names, task/tool roles, post-conditions, plus the core decision logic: each decision predicate with its conditions, thresholds and outcomes, and the rule fact tables (engineers).
 
-The tool extracts a deterministic Mermaid seed, has pi rewrite it in the chosen grade, validates the result, writes the viewer under `.pi/deepclause/diagrams/`, and opens it. The DML file may live anywhere (workspace-relative or absolute); only the generated viewer stays under `.pi/deepclause/`.
+The tool extracts a deterministic Mermaid seed, enriches the specification seed with a `LOGIC` section (decision predicates, guards, thresholds, judgments) and a `RULES` section (fact tables), has pi rewrite it in the chosen grade, validates the result, writes the viewer under `.pi/deepclause/diagrams/`, and opens it. The DML file may live anywhere (workspace-relative or absolute); only the generated viewer stays under `.pi/deepclause/`.
 
 Do not hand-write Mermaid for the user, and do not copy diagram tooling into the workspace. Regenerating a grade replaces only that grade's sidecar (`<name>.presentation.mmd` / `<name>.specification.mmd`).
 

package/src/assets/apply.dml

@@ -85,7 +85,7 @@ attempt(TasksPath, Statuses0, Change, Id, Props, N, Max, Feedback, Statuses) :-
     format(string(Progress), "task ~w attempt ~w/~w", [Id, N, Max]),
     output(Progress),
     execute(Change, Id, Props, Feedback, Summary),
-    verify(Props, Summary, Verdict),
+    verify_task(Props, Summary, Verdict),
     (   Verdict = ok
     ->  sp_set_status(Statuses0, Id, done(N), Statuses),
         sp_write_statuses(TasksPath, Statuses),
@@ -123,7 +123,7 @@ build_instruction(Id, Do, Expected, Feedback, Instruction) :-
         "Task ~w. ~w~nExpected result: ~w~n~nThe previous attempt failed verification: ~w~nFix only what is needed; do not redo the whole task.",
         [Id, Do, Expected, Feedback]).
 
-verify(Props, Summary, Verdict) :-
+verify_task(Props, Summary, Verdict) :-
     catch(get_dict(checks, Props, Checks), _, Checks = []),
     findall(Message, (member(Check, Checks), run_check(Check, Message), Message \= ok), Failures),
     (   Summary == ""

package/src/assets/specs.dml

@@ -64,9 +64,12 @@ sp_sections(Lines, Sections) :-
     sp_skip_plain(Lines, Rest),
     sp_sections_from(Rest, Sections).
 
-sp_skip_plain([line(Line, Number)|Rest], [line(Line, Number)|Rest]) :- sp_heading(Line, Level, _), Level >= 1, Level =< 3, !.
-sp_skip_plain([_|Rest], Out) :- sp_skip_plain(Rest, Out).
 sp_skip_plain([], []).
+sp_skip_plain([Item|Rest], Out) :-
+    (   Item = line(Line, _), sp_heading(Line, Level, _), Level >= 1, Level =< 3
+    ->  Out = [Item|Rest]
+    ;   sp_skip_plain(Rest, Out)
+    ).
 
 sp_sections_from([], []).
 sp_sections_from([line(Line, N)|Rest], [section(Level, Text, N, Body)|More]) :-
@@ -77,12 +80,11 @@ sp_sections_from([line(Line, N)|Rest], [section(Level, Text, N, Body)|More]) :-
     sp_sections_from(Tail, More).
 
 sp_take_body([], [], []).
-sp_take_body([line(Line, Number)|Rest], [], [line(Line, Number)|Rest]) :-
-    sp_heading(Line, Level, _),
-    Level >= 1,
-    Level =< 3,
-    !.
-sp_take_body([Item|Rest], [Item|Body], Tail) :- sp_take_body(Rest, Body, Tail).
+sp_take_body([Item|Rest], Body, Tail) :-
+    (   Item = line(Line, _), sp_heading(Line, Level, _), Level >= 1, Level =< 3
+    ->  Body = [], Tail = [Item|Rest]
+    ;   Body = [Item|Body1], sp_take_body(Rest, Body1, Tail)
+    ).
 
 %% Split a requirement body (level-4 headings inline) into description + scenarios.
 sp_split_scenarios(Body, DescLines, ScenarioSections) :-
@@ -90,11 +92,11 @@ sp_split_scenarios(Body, DescLines, ScenarioSections) :-
     sp_scenario_sections(Rest, ScenarioSections).
 
 sp_take_plain([], [], []).
-sp_take_plain([line(Line, Number)|Rest], [], [line(Line, Number)|Rest]) :-
-    sp_heading(Line, Level, _),
-    Level >= 4,
-    !.
-sp_take_plain([Item|Rest], [Item|Body], Tail) :- sp_take_plain(Rest, Body, Tail).
+sp_take_plain([Item|Rest], Body, Tail) :-
+    (   Item = line(Line, _), sp_heading(Line, Level, _), Level >= 4
+    ->  Body = [], Tail = [Item|Rest]
+    ;   Body = [Item|Body1], sp_take_plain(Rest, Body1, Tail)
+    ).
 
 sp_scenario_sections([], []).
 sp_scenario_sections([line(Line, N)|Rest], [section(4, Text, N, Body)|More]) :-
@@ -103,11 +105,11 @@ sp_scenario_sections([line(Line, N)|Rest], [section(4, Text, N, Body)|More]) :-
     sp_scenario_sections(Tail, More).
 
 sp_take_until_level4([], [], []).
-sp_take_until_level4([line(Line, Number)|Rest], [], [line(Line, Number)|Rest]) :-
-    sp_heading(Line, Level, _),
-    Level >= 4,
-    !.
-sp_take_until_level4([Item|Rest], [Item|Body], Tail) :- sp_take_until_level4(Rest, Body, Tail).
+sp_take_until_level4([Item|Rest], Body, Tail) :-
+    (   Item = line(Line, _), sp_heading(Line, Level, _), Level >= 4
+    ->  Body = [], Tail = [Item|Rest]
+    ;   Body = [Item|Body1], sp_take_until_level4(Rest, Body1, Tail)
+    ).
 
 %% ---------------------------------------------------------------------------
 %% Term extraction
@@ -164,10 +166,11 @@ sp_parse_delta(Text, Deltas) :-
     sp_collect_ops(Rest, Deltas).
 
 sp_drop_to_op([], []).
-sp_drop_to_op([section(2, Header, Number, Body)|Rest], [section(2, Header, Number, Body)|Rest]) :-
-    sp_delta_header(Header, _),
-    !.
-sp_drop_to_op([_|Rest], Out) :- sp_drop_to_op(Rest, Out).
+sp_drop_to_op([Item|Rest], Out) :-
+    (   Item = section(2, Header, _, _), sp_delta_header(Header, _)
+    ->  Out = [Item|Rest]
+    ;   sp_drop_to_op(Rest, Out)
+    ).
 
 sp_collect_ops([], []).
 sp_collect_ops([section(2, Header, _, _)|Rest], Deltas) :-
@@ -184,10 +187,11 @@ sp_collect_ops([section(2, Header, _, _)|Rest], Deltas) :-
     ).
 
 sp_take_until_op([], [], []).
-sp_take_until_op([section(2, Header, Number, Body)|Rest], [], [section(2, Header, Number, Body)|Rest]) :-
-    sp_delta_header(Header, _),
-    !.
-sp_take_until_op([Item|Rest], [Item|Group], Tail) :- sp_take_until_op(Rest, Group, Tail).
+sp_take_until_op([Item|Rest], Group, Tail) :-
+    (   Item = section(2, Header, _, _), sp_delta_header(Header, _)
+    ->  Group = [], Tail = [Item|Rest]
+    ;   Group = [Item|Group1], sp_take_until_op(Rest, Group1, Tail)
+    ).
 
 %% ---------------------------------------------------------------------------
 %% Validation

package/src/config.ts

@@ -2,6 +2,21 @@ import { readFile, writeFile } from "node:fs/promises";
 
 export type ContextMode = "turn" | "branch" | "isolated";
 
+export interface JevJudgeConfig {
+  /** Whether the Jev (TypeSafe System One) backend may be used. */
+  enabled: boolean;
+  /** Model alias or pinned version passed to TypeSafe. */
+  model: string;
+  /** Environment variable holding the TypeSafe API key. */
+  apiKeyEnv: string;
+}
+
+export interface JudgmentConfig {
+  /** Default backend name: "llm", "jev", or a name registered by an extension. */
+  default: string;
+  jev: JevJudgeConfig;
+}
+
 export interface DeepClauseConfig {
   version: 1;
   contextMode: ContextMode;
@@ -10,6 +25,7 @@ export interface DeepClauseConfig {
   maxTokens: number;
   verbose: boolean;
   modelToolEnabled: boolean;
+  judgment: JudgmentConfig;
 }
 
 export const DEFAULT_CONFIG: DeepClauseConfig = {
@@ -20,6 +36,10 @@ export const DEFAULT_CONFIG: DeepClauseConfig = {
   maxTokens: 16_384,
   verbose: false,
   modelToolEnabled: false,
+  judgment: {
+    default: "llm",
+    jev: { enabled: false, model: "jev-latest", apiKeyEnv: "TYPESAFE_API_KEY" },
+  },
 };
 
 const isContextMode = (value: unknown): value is ContextMode =>
@@ -55,6 +75,42 @@ export async function loadConfig(path: string): Promise<DeepClauseConfig> {
     maxTokens: positiveInteger("maxTokens", DEFAULT_CONFIG.maxTokens),
     verbose: config.verbose === true,
     modelToolEnabled: config.modelToolEnabled === true,
+    judgment: parseJudgmentConfig(config.judgment),
+  };
+}
+
+function parseJudgmentConfig(value: unknown): JudgmentConfig {
+  if (value === undefined) return DEFAULT_CONFIG.judgment;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("judgment must be a JSON object");
+  }
+  const judgment = value as Record<string, unknown>;
+  const defaultBackend = judgment.default ?? DEFAULT_CONFIG.judgment.default;
+  if (typeof defaultBackend !== "string" || !defaultBackend.trim()) {
+    throw new Error("judgment.default must be a non-empty backend name");
+  }
+
+  const jevValue = judgment.jev ?? {};
+  if (!jevValue || typeof jevValue !== "object" || Array.isArray(jevValue)) {
+    throw new Error("judgment.jev must be a JSON object");
+  }
+  const jev = jevValue as Record<string, unknown>;
+  const model = jev.model ?? DEFAULT_CONFIG.judgment.jev.model;
+  const apiKeyEnv = jev.apiKeyEnv ?? DEFAULT_CONFIG.judgment.jev.apiKeyEnv;
+  if (typeof model !== "string" || !model.trim()) {
+    throw new Error("judgment.jev.model must be a non-empty string");
+  }
+  if (typeof apiKeyEnv !== "string" || !apiKeyEnv.trim()) {
+    throw new Error("judgment.jev.apiKeyEnv must be a non-empty environment variable name");
+  }
+
+  return {
+    default: defaultBackend.trim(),
+    jev: {
+      enabled: jev.enabled === true,
+      model: model.trim(),
+      apiKeyEnv: apiKeyEnv.trim(),
+    },
   };
 }
 
@@ -72,3 +128,38 @@ export async function setModelToolEnabled(configPath: string, enabled: boolean):
   await writeFile(configPath, `${JSON.stringify({ ...existing, modelToolEnabled: enabled }, null, 2)}\n`, "utf8");
   return loadConfig(configPath);
 }
+
+export interface JudgeConfigPatch {
+  /** Default backend name ("llm" or "jev"). */
+  default?: string;
+  /** Partial update of the Jev backend settings. */
+  jev?: Partial<JevJudgeConfig>;
+}
+
+/** Merge a judgment patch into the workspace config, preserving every other field. */
+export async function setJudgeConfig(
+  configPath: string,
+  patch: JudgeConfigPatch,
+): Promise<DeepClauseConfig> {
+  let existing: Record<string, unknown> = {};
+  try {
+    const parsed: unknown = JSON.parse(await readFile(configPath, "utf8"));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) existing = parsed as Record<string, unknown>;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw new Error(`Invalid DeepClause config: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  const record = (value: unknown): Record<string, unknown> =>
+    value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+
+  const nextJudgment = {
+    ...record(existing.judgment),
+    ...(patch.default !== undefined ? { default: patch.default } : {}),
+    jev: { ...record(record(existing.judgment).jev), ...(patch.jev ?? {}) },
+  };
+
+  await writeFile(configPath, `${JSON.stringify({ ...existing, judgment: nextJudgment }, null, 2)}\n`, "utf8");
+  return loadConfig(configPath);
+}