@protokol11/pi-judgment 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 protokol11
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# @protokol11/pi-judgment
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed, calibrated decisions for pi agents: a `judge` tool, an append-only ledger, a reliability curve, and a scope-lock gate with dual-judge review.
+
+## Why
+
+Agents get autonomy through a prompt. This extension grounds autonomy in evidence instead:
+
+1. Every agent decision is recorded as a typed judgment with an explicit confidence.
+2. Resolved outcomes build a calibration curve per model. The curve decides when a model's probability is trustworthy enough to act on.
+3. Escalation to a human is a priced third action, not a fallback. Below the minimum sample size, every decision escalates: a cold-start ledger has no evidence, so the human decides.
+
+## How it works
+
+Mental model: `judge(state, questions)` asks typed questions and returns answers with a probability. Each answer lands in an append-only ledger. Later, `resolve_judgment` records whether the claim turned out true. The calibration view compares predicted vs. observed accuracy per confidence bin.
+
+```text
+agent ── judge(state, questions) ──► lint questions (free: no model call on bad input)
+                                      │
+                                      ▼
+                          model answers noul / choice / score
+                          (yes/no + probability, or option, or score)
+                                      │
+                                      ▼
+                 append-only ledger: .pi/judgments.jsonl
+                 judgment rows + resolution + refusal events, folded on read
+                                      │
+        resolve_judgment(id, outcome) ▼
+                 reliability curve: predicted vs. observed per bin
+                 /judgments → Tab: calibration pane
+```
+
+Scope-lock gate: `write` and `edit` are blocked until a scope judgment is authorized. A deterministic rule predicate runs first (an explicit user trigger pins p, no model call). If no trigger is present, a semantic judge scores the residue of the conversation. A degraded judge never degrades to allow: it asks the human. Authorization is bound to the session that declared it and is inherited by subagents through the session chain (a child reads the root project's ledger).
+
+Decision policy (`decide`): act yes, act no, or escalate — the policy picks the cheapest action, and a tie escalates to the human. Below `minSample` resolved records it always escalates.
+
+- `judge(state, questions, model?)` — typed questions (`noul`, `choice`, `score`), linted before any model call; bad questions cost nothing.
+- `resolve_judgment(judgment_id, outcome)` — records ground truth; unresolved judgments never count toward calibration.
+- `scope_lock(declared_scope)` — authorizes file mutations for the session; call before the first `write`/`edit`.
+- `/judgments` — full-screen explorer over the ledger: browse, filter by model and provenance, resolve with `y`/`n`; `Tab` switches to the calibration pane. Outside the TUI it prints a one-line stats summary.
+
+## Install
+
+Requires Node 22 or later. For the pi coding agent:
+
+```bash
+pi install npm:@protokol11/pi-judgment
+```
+
+Or add the package to `packages` in your pi settings. See pi.dev for the extension API.
+
+## Optional integration: cp-review gate
+
+The gate reviews `write`/`edit` payloads against CPs (composable principles) from a trained classifier. By default it reads the corpus at `~/.agents/skills/principles-render/rendered/cp-corpus.json`. That file comes from the `principles-render` skill in the `principles` package: https://github.com/protokol11/principles
+
+Without a corpus, or when the classifier is unavailable, the gate fails loudly with `classifier/corpus unavailable` and asks for human review. There is no silent fallback.
+
+## Honest status
+
+Working. 16 test files, 142 tests passing. The cp gate caches the corpus per process; a session-level cache is not implemented.
+
+## License
+
+MIT

package/extensions/commands.ts

@@ -0,0 +1,143 @@
+// commands.ts — thin wiring for the /judgments command. No logic: read ledger,
+// hand state to the pure renderer, map keys to state transitions. The state
+// builder and the y/n decision live in pure modules (explorer-state.ts,
+// core/resolve-plan.ts) so `node --test` can drive them without the pi UI layer.
+// Prior art: session-manager/commands.ts (ctx.ui.custom + keyDispatch, V008).
+import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { join } from "node:path";
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
+import { appendResolution, readJudgments } from "./core/ledger.ts";
+import { judgmentStats, nextProvenance } from "./core/stats.ts";
+import { planResolution } from "./core/resolve-plan.ts";
+import { nextGroup, openingGroup, toExplorerState, type ExplorerViewState } from "./explorer-state.ts";
+import { bodyFor, renderJudgments } from "./explorer.ts";
+
+type ViewState = ExplorerViewState;
+
+function applyTheme(theme: Theme, s: { text: string; color?: string }): string {
+  if (!s.color || s.color === "default") return s.text;
+  return theme.fg(s.color as Parameters<Theme["fg"]>[0], s.text);
+}
+
+export function registerJudgmentsCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("judgments", {
+    description: "Full-screen explorer over the judgment ledger: calibration, browse, resolve",
+    handler: async (_args, ctx) => {
+      const ledgerPath = join(ctx.cwd, CONFIG_DIR_NAME, "judgments.jsonl");
+      if (ctx.mode !== "tui" || !ctx.hasUI) {
+        const stats = judgmentStats(readJudgments(ledgerPath));
+        ctx.ui.notify(
+          `judgments: ${stats.total} records, ${stats.resolved} resolved, ${stats.pending} pending (open in TUI for the explorer)`,
+          "info"
+        );
+        return;
+      }
+
+      const v: ViewState = {
+        view: "ledger",
+        modelFilter: null,
+        provenanceFilter: "judge",
+        pendingOnly: true,
+        questionGroup: null, // null = open on openingGroup(); `g` fills it in
+        selected: 0,
+        message: null,
+        help: false,
+        height: 24,
+        records: readJudgments(ledgerPath),
+      };
+
+      await ctx.ui.custom<string | null>(
+        (tui, theme, _kb, done) => ({
+          render(width: number): string[] {
+            // Reserve two columns for the side borders and two rows for the top
+            // and bottom borders, so the box stays inside the overlay bounds.
+            const rows = Math.max(10, Math.floor(tui.terminal.rows * 0.85));
+            const height = Math.max(8, rows - 3);
+            v.height = height; // paging matches the window the renderer just laid out
+            const inner = Math.max(1, width - 2);
+            const frame = (s: string) => theme.fg("border", s);
+            const body = renderJudgments({ ...toExplorerState(v, height, width) }).map((line) =>
+              line.map((s) => applyTheme(theme, s)).join("")
+            );
+            const out: string[] = [frame(`╭${"─".repeat(inner)}╮`)];
+            for (const line of body) {
+              const clipped = truncateToWidth(line, inner, "");
+              out.push(frame("│") + clipped + " ".repeat(Math.max(0, inner - visibleWidth(clipped))) + frame("│"));
+            }
+            out.push(frame(`╰${"─".repeat(inner)}╯`));
+            return out;
+          },
+        invalidate() {},
+        handleInput(data: string) {
+          v.message = null;
+          if (matchesKey(data, Key.escape) || data === "q") {
+            done(null);
+            return;
+          }
+          const state = toExplorerState(v, v.height, 0);
+          const last = Math.max(0, state.rows.length - 1);
+          const clamp = (n: number) => Math.max(0, Math.min(last, n));
+          if (matchesKey(data, Key.up) || matchesKey(data, Key.down)) {
+            v.selected = clamp(v.selected + (matchesKey(data, Key.up) ? -1 : 1));
+          } else if (matchesKey(data, Key.pageUp) || matchesKey(data, Key.pageDown)) {
+            const page = bodyFor(v.height);
+            v.selected = clamp(v.selected + (matchesKey(data, Key.pageUp) ? -page : page));
+          } else if (matchesKey(data, Key.home)) {
+            v.selected = 0;
+          } else if (matchesKey(data, Key.end)) {
+            v.selected = last;
+          } else if (data === "\t") {
+            v.view = v.view === "ledger" ? "calibration" : "ledger";
+          } else if (matchesKey(data, Key.question)) {
+            v.help = !v.help;
+          } else if (data === "f") {
+            v.pendingOnly = !v.pendingOnly;
+            v.selected = 0;
+          } else if (data === "m") {
+            const models = judgmentStats(v.records).models;
+            const i = v.modelFilter ? models.indexOf(v.modelFilter) : -1;
+            v.modelFilter = i + 1 < models.length ? models[i + 1] : null;
+            v.selected = 0;
+          } else if (data === "p") {
+            // Cycle the provenances the ledger actually holds, so `code` and
+            // `classifier` rows are reachable; the curve stays one family at a
+            // time (mixed provenances would blur it).
+            v.provenanceFilter = nextProvenance(
+              v.records.map((r) => r.provenance),
+              v.provenanceFilter
+            );
+            v.selected = 0;
+          } else if (data === "g") {
+            // Cycle only the groups the current model + provenance filter leaves,
+            // so `g` never lands on a pane that would render another filter's rows.
+            const current = v.questionGroup ?? openingGroup(v.records, v.modelFilter, v.provenanceFilter);
+            v.questionGroup = nextGroup(v.records, current, v.modelFilter, v.provenanceFilter);
+            v.selected = 0;
+          } else if ((data === "y" || data === "n") && v.view === "ledger") {
+            // A verdict is only ever written for a row the reader can see: no
+            // write from the calibration pane and none on an already-resolved row.
+            const plan = planResolution(state.rows, v.selected);
+            if (plan.kind === "write") {
+              const row = plan.row;
+              const target = v.records.find((r) => r.ts === row.ts && r.question_id === row.question_id);
+              if (target) {
+                appendResolution(ledgerPath, target.judgment_id, data === "y", new Date().toISOString());
+                v.records = readJudgments(ledgerPath);
+                v.message = `resolved ${target.judgment_id} → ${data === "y"}`;
+                // The resolved row leaves the queue, so the cursor can point past
+                // the end; toExplorerState clamps `selected` into the new rows.
+                toExplorerState(v, v.height, 0);
+              }
+            } else if (plan.kind === "already-resolved") {
+              v.message = "already resolved";
+            }
+          }
+          tui.requestRender();
+        },
+        }),
+        { overlay: true, overlayOptions: { anchor: "center", width: "90%", maxHeight: "85%", margin: 1 } }
+      );
+    },
+  });
+}

package/extensions/core/cp-corpus.ts

@@ -0,0 +1,68 @@
+// core/cp-corpus.ts — the CP corpus the gate reviews diffs against.
+//
+// Source of truth: principles-render emits rendered/cp-corpus.json from the
+// to-violations catalog (render.mjs owns YAML parsing; DRY). This module only
+// validates a JSON string into typed entries — no fs, no pi import.
+import type { Question } from "./types.ts";
+
+export const CP_SEVERITIES = ["must", "should"] as const;
+export type CpSeverity = (typeof CP_SEVERITIES)[number];
+
+export interface CpEntry {
+  id: string;
+  severity: CpSeverity;
+  statement: string;
+}
+
+export interface CpCorpus {
+  generated_from?: string;
+  cps: CpEntry[];
+}
+
+/** Parse and validate a corpus JSON string. Throws naming the offending entry. */
+export function parseCorpus(json: string): CpCorpus {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(json);
+  } catch (e) {
+    throw new Error(`cp-corpus: invalid JSON (${(e as Error).message})`);
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("cp-corpus: top level must be an object");
+  }
+  const obj = raw as Record<string, unknown>;
+  if (!Array.isArray(obj.cps)) throw new Error("cp-corpus: missing cps array");
+  const cps: CpEntry[] = obj.cps.map((entry, i) => {
+    const where = `cps[${i}]`;
+    if (!entry || typeof entry !== "object") throw new Error(`cp-corpus: ${where} not an object`);
+    const e = entry as Record<string, unknown>;
+    if (typeof e.id !== "string" || !e.id) throw new Error(`cp-corpus: ${where} missing id`);
+    if (!CP_SEVERITIES.includes(e.severity as CpSeverity)) {
+      throw new Error(`cp-corpus: ${e.id} bad severity ${String(e.severity)}`);
+    }
+    if (typeof e.statement !== "string" || !e.statement.trim()) {
+      throw new Error(`cp-corpus: ${e.id} missing statement`);
+    }
+    return { id: e.id, severity: e.severity as CpSeverity, statement: e.statement };
+  });
+  const seen = new Set<string>();
+  for (const cp of cps) {
+    if (seen.has(cp.id)) throw new Error(`cp-corpus: duplicate id ${cp.id}`);
+    seen.add(cp.id);
+  }
+  return {
+    generated_from: typeof obj.generated_from === "string" ? obj.generated_from : undefined,
+    cps,
+  };
+}
+
+export function mustCps(corpus: CpCorpus): CpEntry[] {
+  return corpus.cps.filter((c) => c.severity === "must");
+}
+
+export function shouldCps(corpus: CpCorpus): CpEntry[] {
+  return corpus.cps.filter((c) => c.severity === "should");
+}
+
+/** Kept import-side: Question is the wire shape buildQuestions emits. */
+export type { Question };

package/extensions/core/cp-gate.ts

@@ -0,0 +1,192 @@
+// core/cp-gate.ts — pure cp-review gate: questions in, verdicts out.
+//
+// The trained cell speaks the S1 wire: state {diff, cp_texts} with one
+// cp-review:CP-XX noul question per should-CP. The drilled operating point
+// (sess-drill-rlcd-operating-point) is applied per call here and only here:
+// violated = P(yes) >= CP_GATE_THRESHOLD. decide() and scope-lock stay
+// untouched. No fs, no model, no pi import.
+import { CP_REVIEW_PREFIX } from "./cp-review.ts";
+import type { CpEntry } from "./cp-corpus.ts";
+import type { Answer, Question } from "./types.ts";
+
+/** Drilled BA operating point; per-call, not baked into decide(). */
+export const CP_GATE_THRESHOLD = 0.081149;
+
+/** One gate review: the diff under edit plus the CP texts it is judged against. */
+export interface CpReviewState {
+  diff: string;
+  cp_texts: Record<string, string>;
+}
+
+export interface GateQuestion {
+  questions: Record<string, Question>;
+  state: CpReviewState;
+}
+
+/**
+ * Build the classifier request for one diff. Instruction shape matches the
+ * cell's training wire verbatim (calibration-warmup corpus) with the CP id
+ * substituted — the cell was trained on this exact phrasing.
+ */
+export function buildQuestions(diff: string, cps: CpEntry[]): GateQuestion {
+  const questions: Record<string, Question> = {};
+  const cp_texts: Record<string, string> = {};
+  for (const cp of cps) {
+    cp_texts[cp.id] = cp.statement;
+    questions[`${CP_REVIEW_PREFIX}${cp.id}`] = {
+      type: "noul",
+      instructions:
+        `Same diff in state.diff. Full principle text in state.cp_texts under key ${cp.id}. ` +
+        `Does this diff violate principle ${cp.id}? yes/no with probability.`,
+    };
+  }
+  return { questions, state: { diff, cp_texts } };
+}
+
+export interface Verdict {
+  cp_id: string;
+  /** P(violation) recovered from the answer; finite, in [0,1]. */
+  p: number;
+  violated: boolean;
+}
+
+export interface VerdictError {
+  cp_id: string;
+  error: string;
+}
+
+export interface GateVerdicts {
+  verdicts: Verdict[];
+  errors: VerdictError[];
+}
+
+function sanitizeConfidence(raw: unknown): number | null {
+  if (typeof raw !== "number" || !Number.isFinite(raw)) return null;
+  if (raw < 0 || raw > 1) return null;
+  return raw;
+}
+
+/**
+ * Turn judgment answers into verdicts at the operating point. `confidence` is
+ * P(recorded value) (ADR-0045), so P(yes) is reconstructed before the
+ * comparison: pYes = value === "yes" ? confidence : 1 - confidence. The
+ * verdict fills `p` with pYes — the same quantity the cell's raw probability
+ * used to carry — so thresholds, reported p values and sort order stay
+ * bit-for-bit identical to the pre-ADR-0045 records. Comparison is >= (prototype
+ * edge p == t → violated). Answers with non-finite or out-of-range confidence
+ * surface as errors, never as a clean verdict; so does a value that is neither
+ * "yes" nor "no", which names no direction to threshold on. An unanswered CP
+ * produces no row at all (HUMAN-JUDGMENT-FINAL: no row, not violated:false).
+ * Verdicts sort by p (pYes) desc.
+ */
+export function verdictsFromAnswers(
+  answers: Record<string, Answer>,
+  threshold: number = CP_GATE_THRESHOLD
+): GateVerdicts {
+  const verdicts: Verdict[] = [];
+  const errors: VerdictError[] = [];
+  for (const [id, a] of Object.entries(answers)) {
+    const cp_id = id.startsWith(CP_REVIEW_PREFIX) ? id.slice(CP_REVIEW_PREFIX.length) : id;
+    if (!a || typeof a !== "object") {
+      errors.push({ cp_id, error: "missing answer" });
+      continue;
+    }
+    const p = sanitizeConfidence(a.confidence);
+    if (p === null) {
+      errors.push({ cp_id, error: `bad confidence ${String(a.confidence)}` });
+      continue;
+    }
+    // Only a yes/no value names a direction. Anything else has no P(yes) to
+    // recover, so it errors out instead of silently inverting one.
+    if (a.value !== "yes" && a.value !== "no") {
+      errors.push({ cp_id, error: `unsupported value ${String(a.value)}` });
+      continue;
+    }
+    // confidence is P(value); the gate thresholds on P(yes), so invert "no".
+    const pYes = a.value === "yes" ? p : 1 - p;
+    verdicts.push({ cp_id, p: pYes, violated: pYes >= threshold });
+  }
+  verdicts.sort((x, y) => y.p - x.p);
+  return { verdicts, errors };
+}
+
+/**
+ * The must-CP slot. Predicates are synthesized by rule-lifecycle promotion
+ * (ADR-0034) and registered here; the registry ships empty — no deterministic
+ * predicates exist for the 31 must-CPs yet, and inventing them would be a lie.
+ * check returns a violation reason or null.
+ */
+export interface LintPredicate {
+  id: string;
+  check: (content: string) => string | null;
+}
+
+export const lintRegistry: LintPredicate[] = [];
+
+/** Run registered must-lint predicates over the payload. Empty registry passes. */
+export function runLints(content: string, registry: LintPredicate[] = lintRegistry): VerdictError[] {
+  const hits: VerdictError[] = [];
+  for (const pred of registry) {
+    const reason = pred.check(content);
+    if (reason !== null) hits.push({ cp_id: pred.id, error: reason });
+  }
+  return hits;
+}
+
+/**
+ * The hook's decision, planned pure from gate outputs. Typed union (CP-50):
+ * allow — proceed; notice — proceed, the caller surfaces why the gate stood
+ * down (oversized payload, own-infra failure); block — hard stop (lint hit,
+ * or verdict/escalation with no UI to ask); confirm — ask the human (verdict
+ * override or classifier-failure escalation).
+ */
+export type GateDecision =
+  | { action: "allow"; reason: string }
+  | { action: "notice"; reason: string }
+  | { action: "block"; reason: string; kind: "lint" | "no-ui" }
+  | { action: "confirm"; reason: string; violated: Verdict[] | null };
+
+export interface GatePlanInput {
+  gateEnabled: boolean;
+  contentLength: number;
+  cap: number;
+  /** Own-infra failure (corpus unreadable/unparseable). Degrades open, loudly. */
+  infraError: string | null;
+  lintHits: VerdictError[];
+  /** Classifier unavailable or judge returned errors. Escalates, never a silent no. */
+  classifyError: string | null;
+  verdicts: Verdict[];
+  hasUI: boolean;
+}
+
+export function planGateDecision(input: GatePlanInput): GateDecision {
+  if (!input.gateEnabled) return { action: "allow", reason: "cp-review gate off (CP_REVIEW_GATE=off)" };
+  if (input.contentLength > input.cap) {
+    return {
+      action: "notice",
+      reason: `cp-review gate: payload ${input.contentLength} chars exceeds ${input.cap}-char review cap; written UNREVIEWED (full-diff retrieval is a lab-side step)`,
+    };
+  }
+  if (input.infraError) {
+    return { action: "notice", reason: `cp-review gate: own infra down (${input.infraError}); written UNREVIEWED` };
+  }
+  if (input.lintHits.length) {
+    const names = input.lintHits.map((h) => `${h.cp_id}: ${h.error}`).join("; ");
+    return { action: "block", kind: "lint", reason: `cp-review gate (must-CP lint): ${names}` };
+  }
+  if (input.classifyError) {
+    const reason = `cp-review gate: classifier failure — ${input.classifyError}. No guess recorded; a human decides.`;
+    return input.hasUI
+      ? { action: "confirm", reason, violated: null }
+      : { action: "block", kind: "no-ui", reason: `${reason} (no UI: request human review)` };
+  }
+  const violated = input.verdicts.filter((v) => v.violated);
+  if (violated.length) {
+    const names = violated.map((v) => `${v.cp_id} (p=${v.p.toFixed(3)})`).join(", ");
+    const reason = `cp-review gate: suspected violation(s) at t=${CP_GATE_THRESHOLD}: ${names}. Confirm to override.`;
+    return input.hasUI
+      ? { action: "confirm", reason, violated }
+      : { action: "block", kind: "no-ui", reason: `${reason} (no UI: request human review)` };
+  }
+  return { action: "allow", reason: "cp-review gate: clean" };
+}

package/extensions/core/cp-review.ts

@@ -0,0 +1,76 @@
+// core/cp-review.ts — the pure cp-review request/answer contract.
+//
+// The RLCD cell speaks the classifier wire: one `bool` question with
+// criteria {true,false} answers with {type:"bool", probability}. The judgment
+// engine speaks `noul` questions and {value, confidence} answers. This module
+// is the only place that translates between the two, and the only place that
+// names the request shape. No model, no fs, no pi import.
+import type { Answer, Question } from "./types.ts";
+
+/** Question-id prefix that marks a request for the trained cp-review cell. */
+export const CP_REVIEW_PREFIX = "cp-review:";
+
+export function isCpReviewQuestion(id: string): boolean {
+  return id.startsWith(CP_REVIEW_PREFIX);
+}
+
+/**
+ * All-or-nothing route: a request goes to the classifier only when every
+ * question is a cp-review question. A mixed request keeps the generative path,
+ * so one state_hash is never split across two models.
+ */
+export function isCpReviewRequest(questions: Record<string, { type: string }>): boolean {
+  const ids = Object.keys(questions);
+  return ids.length > 0 && ids.every(isCpReviewQuestion);
+}
+
+/** Classifier wire question: fixed yes/no criteria, per the S1 prototype. */
+export interface ClassifierBoolQuestion {
+  type: "bool";
+  instructions: string;
+  criteria: { true: string; false: string };
+  /** Per-question CP key (cp-review questions only): lets the sidecar align the CP
+   * text without parsing the id string. See ADR-0039. */
+  cp_key?: string;
+}
+
+/** Map judgment `noul` questions to the classifier `bool` wire shape. */
+export function toClassifierQuestions(questions: Record<string, Question>): Record<string, ClassifierBoolQuestion> {
+  const out: Record<string, ClassifierBoolQuestion> = {};
+  for (const [id, q] of Object.entries(questions)) {
+    out[id] = {
+      type: "bool",
+      instructions: q.instructions,
+      criteria: { true: "yes", false: "no" },
+    };
+    // The CP key is derived from the single id-format source (CP_REVIEW_PREFIX);
+    // the sidecar reads the field and never parses the id (ADR-0039).
+    if (isCpReviewQuestion(id)) out[id].cp_key = id.slice(CP_REVIEW_PREFIX.length);
+  }
+  return out;
+}
+
+/** Classifier wire answer; only `bool` carries a probability. */
+export interface ClassifierBoolAnswer {
+  type: string;
+  probability?: number;
+}
+
+/**
+ * Map classifier answers back to judgment answers. The value is the point
+ * guess at the 0.5 boundary; `confidence` is P(recorded value) — the raw
+ * probability for "yes", its complement for "no" (ADR-0045). A caller that
+ * thresholds on P(yes), like the cp-review gate, must invert explicitly.
+ */
+export function toJudgmentAnswers(answers: Record<string, ClassifierBoolAnswer>): Record<string, Answer> {
+  const out: Record<string, Answer> = {};
+  for (const [id, a] of Object.entries(answers)) {
+    const p = typeof a.probability === "number" && Number.isFinite(a.probability) ? a.probability : 0.5;
+    const clamped = Math.min(1, Math.max(0, p));
+    out[id] =
+      clamped >= 0.5
+        ? { value: "yes", confidence: clamped }
+        : { value: "no", confidence: 1 - clamped };
+  }
+  return out;
+}