@codedology/code-forge 0.1.0

package/src/decide/jev-client.mjs

@@ -0,0 +1,216 @@
+/**
+ * The Jev (System 1) HTTP transport (plan §3.1, §3.2, O22). This module owns exactly one job:
+ * turn `{state, questions}` into one `POST` to Jev and a typed result — nothing here decides
+ * WHETHER to call Jev, picks a fallback, or writes a ledger row (that is `fallback-rules.mjs`,
+ * the CLI verb, and later blocks).
+ *
+ * **Verified request/response shape (research/jev/jev_test.py + jev_results.json, this Mac,
+ * 2026-09-24; plan header `[A10]`):** `POST https://api.typesafe.ai/v1/systemone`, header
+ * `Authorization: Bearer <key>`, body `{state, model, questions}` where each `questions.<id>` is
+ * `{type: "noul"|"choice"|"score", instructions, criteria}`. A successful response body is
+ * `{answers: {<id>: <typed answer>}, usage?: {input_tokens, output_tokens}}` — `choice` answers
+ * come back `{type, choice, probabilities, confidence}`, `score` `{type, score, legend,
+ * probabilities, confidence}`, `noul` `{type, noul}` (a PROBABILITY that the statement is true,
+ * NOT a confidence — `thresholds.mjs` computes confidence/margin itself, per O8; this module never
+ * reads those API-supplied `confidence` fields).
+ *
+ * **Security (rule 6, O22):** the key is read from `opts.key` (a plaintext the caller already
+ * resolved via B2's chain) and used ONLY in the `Authorization` header — never in the request
+ * body, never interpolated into an error message or a log line. This module never calls
+ * `registerSecret` itself (the resolver already did, per `src/keys/store.mjs`); it just never
+ * prints the value. Every error path here carries only a `kind`/`status`/`requestId` — HTTP
+ * status codes and header names, not response bodies that might echo request content back.
+ *
+ * **Retries (§3.5):** 429 (rate limited), 529 (overloaded), a network failure (fetch rejects) and
+ * a per-attempt TIMEOUT (fix round 1 — see below) back off `0.5 s → 2 s → 8 s` between attempts
+ * (3 retries after the first try = 4 attempts total), then give up and report the failure — the
+ * CALLER decides what "give up" means (fallback rules, one banner). 401 (bad/expired key) and 422
+ * (malformed request) never retry: a retry cannot fix either.
+ *
+ * **Per-attempt timeout (fix round 1, review finding "no per-attempt timeout"):** every attempt
+ * carries `signal: AbortSignal.timeout(timeoutMs)` (default `DEFAULT_JEV_TIMEOUT_MS`, 30 s — a
+ * generous headroom over Jev's documented ~0.5 s response time, not a measured server-side bound;
+ * `[A10]` names no server timeout to match). Without this, the only limit was undici's own
+ * default `headersTimeout`/`bodyTimeout` (~300 s), so 4 attempts could block for ~20 minutes
+ * before §3.5's fallback ever got control — far too long for an interactive `jev ask`. An abort
+ * is reported as `kind: 'timeout'` and retries on the SAME backoff as a network failure.
+ */
+
+/** The one Jev endpoint (verified 2026-09-24). */
+export const JEV_URL = 'https://api.typesafe.ai/v1/systemone';
+
+/** The model id Jev's own API expects — not one of `levels.Lx`'s model ids (verified). */
+export const JEV_MODEL = 'jev-latest';
+
+/** Backoff delays between retryable attempts, in milliseconds (§3.5: "0.5 s → 2 s → 8 s"). */
+export const RETRY_DELAYS_MS = Object.freeze([500, 2000, 8000]);
+
+/** Default per-attempt timeout (fix round 1) — see the module header for why 30 s. */
+export const DEFAULT_JEV_TIMEOUT_MS = 30000;
+
+/** HTTP statuses that never retry — a wait cannot fix a bad key or a malformed request. */
+const TERMINAL_STATUS_KINDS = Object.freeze({ 401: 'unauthorized', 422: 'invalid_request' });
+
+/** HTTP statuses that DO retry, per the backoff schedule above. */
+const RETRYABLE_STATUS_KINDS = Object.freeze({ 429: 'rate_limited', 529: 'unavailable' });
+
+/**
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * @param {Response} response
+ * @returns {Promise<string|null>} a request id from the JSON body's `request_id`/`requestId`, else
+ *   from an `x-request-id` header, else `null` — never anything else from the body (rule: no
+ *   parser excerpts in a message).
+ */
+async function requestIdOf(response) {
+  const header = response.headers?.get?.('x-request-id');
+  if (typeof header === 'string' && header.length > 0) {
+    return header;
+  }
+  try {
+    const body = await response.clone().json();
+    const id = body?.request_id ?? body?.requestId;
+    return typeof id === 'string' && id.length > 0 ? id : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @typedef {{type: 'choice', choice: string, probabilities: Record<string, number>}} ChoiceAnswer
+ * @typedef {{type: 'score', score: number, legend: Record<string, string>, probabilities: Record<string, number>}} ScoreAnswer
+ * @typedef {{type: 'noul', noul: number}} NoulAnswer
+ * @typedef {ChoiceAnswer|ScoreAnswer|NoulAnswer} JevAnswer
+ *
+ * @typedef {object} JevQuestionSpec
+ * @property {'choice'|'score'|'noul'} type
+ * @property {string} instructions
+ * @property {Record<string, string>} criteria
+ *
+ * @typedef {object} JevSuccess
+ * @property {true} ok
+ * @property {Record<string, JevAnswer>} answers
+ * @property {{input_tokens?: number, output_tokens?: number}|undefined} usage
+ * @property {number} attempts
+ * @property {number} ms
+ *
+ * @typedef {object} JevFailure
+ * @property {false} ok
+ * @property {'unauthorized'|'invalid_request'|'rate_limited'|'unavailable'|'network'|'timeout'|'unexpected_status'|'invalid_response'} kind
+ * @property {number|null} status
+ * @property {string|null} requestId
+ * @property {number} attempts
+ */
+
+/**
+ * One typed call to Jev, with the documented retry/backoff for 429/529/network. Never throws for
+ * a normal failure (bad key, rate limit, …) — always resolves to `{ok, ...}`; only a caller
+ * programming error (bad `argv` shape) throws synchronously, before any network call.
+ *
+ * @param {object} opts
+ * @param {Record<string, any>} opts.state
+ * @param {Record<string, JevQuestionSpec>} opts.questions
+ * @param {string} opts.key - a plaintext already resolved by the caller (B2's chain). Used ONLY
+ *   in the `Authorization` header.
+ * @param {typeof fetch} [opts.fetch] - defaults to Node's global `fetch`; tests always inject one.
+ * @param {string} [opts.url]
+ * @param {string} [opts.model]
+ * @param {(ms: number) => Promise<void>} [opts.sleep] - injectable so a test never really waits.
+ * @param {() => number} [opts.now]
+ * @param {number} [opts.timeoutMs] - per-attempt timeout; default {@link DEFAULT_JEV_TIMEOUT_MS}.
+ * @returns {Promise<JevSuccess|JevFailure>}
+ */
+export async function askJev({
+  state,
+  questions,
+  key,
+  fetch: fetchImpl = globalThis.fetch,
+  url = JEV_URL,
+  model = JEV_MODEL,
+  sleep = defaultSleep,
+  now = Date.now,
+  timeoutMs = DEFAULT_JEV_TIMEOUT_MS,
+}) {
+  if (state === null || typeof state !== 'object' || Array.isArray(state)) {
+    throw new TypeError('askJev: state must be a plain object');
+  }
+  if (questions === null || typeof questions !== 'object' || Object.keys(questions).length === 0) {
+    throw new TypeError('askJev: questions must be a non-empty object');
+  }
+  if (typeof key !== 'string' || key.length === 0) {
+    throw new TypeError('askJev: key must be a non-empty string');
+  }
+  if (typeof fetchImpl !== 'function') {
+    throw new TypeError('askJev: no fetch implementation available (Node < 18, or none injected)');
+  }
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new TypeError('askJev: timeoutMs must be a finite number > 0');
+  }
+
+  const body = JSON.stringify({ state, model, questions });
+  const started = now();
+  const maxAttempts = RETRY_DELAYS_MS.length + 1;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    /** @type {Response} */
+    let response;
+    try {
+      response = await fetchImpl(url, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' },
+        body,
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+    } catch (err) {
+      // Network failure (DNS, refused connection, …) or OUR OWN per-attempt timeout firing — the
+      // exact error text may carry ambient details we never want to log; only a `kind` survives
+      // past this catch. `AbortSignal.timeout()` aborts with a `TimeoutError` DOMException; any
+      // other rejection (connection refused, DNS failure, …) is the generic "network" kind.
+      const kind = err?.name === 'TimeoutError' ? 'timeout' : 'network';
+      if (attempt < maxAttempts) {
+        await sleep(RETRY_DELAYS_MS[attempt - 1]);
+        continue;
+      }
+      return { ok: false, kind, status: null, requestId: null, attempts: attempt };
+    }
+
+    if (response.ok) {
+      let parsed;
+      try {
+        parsed = await response.json();
+      } catch {
+        return { ok: false, kind: 'invalid_response', status: response.status, requestId: null, attempts: attempt };
+      }
+      if (parsed === null || typeof parsed !== 'object' || parsed.answers === null || typeof parsed.answers !== 'object') {
+        return { ok: false, kind: 'invalid_response', status: response.status, requestId: null, attempts: attempt };
+      }
+      return { ok: true, answers: parsed.answers, usage: parsed.usage, attempts: attempt, ms: now() - started };
+    }
+
+    const status = response.status;
+    if (Object.hasOwn(TERMINAL_STATUS_KINDS, status)) {
+      const requestId = await requestIdOf(response);
+      return { ok: false, kind: TERMINAL_STATUS_KINDS[status], status, requestId, attempts: attempt };
+    }
+    if (Object.hasOwn(RETRYABLE_STATUS_KINDS, status)) {
+      if (attempt < maxAttempts) {
+        await sleep(RETRY_DELAYS_MS[attempt - 1]);
+        continue;
+      }
+      return { ok: false, kind: RETRYABLE_STATUS_KINDS[status], status, requestId: null, attempts: attempt };
+    }
+    // An undocumented status: fail fast rather than guess at retry semantics for it.
+    return { ok: false, kind: 'unexpected_status', status, requestId: null, attempts: attempt };
+  }
+
+  // Unreachable: the loop always returns by `maxAttempts`. Kept only so a mutant that breaks the
+  // loop bound cannot silently fall through to `undefined`.
+  /* c8 ignore next */
+  return { ok: false, kind: 'network', status: null, requestId: null, attempts: maxAttempts };
+}

package/src/decide/questions.mjs

@@ -0,0 +1,161 @@
+/**
+ * The S1 question registry (plan §3.2) — the seven typed questions Jev (or a fallback source)
+ * answers, verbatim from the plan's table: `lane`, `risk`, `security_sensitive`, `next`, `scope`,
+ * `defect`, `resolved`. Each entry's `type`/`instructions`/`criteria` is exactly what
+ * `jev-client.mjs`'s `questions.<id>` argument needs; `fires` and `state` are documentation only
+ * (they describe WHEN a caller asks and WHAT it puts in `state` — no code here builds `state`,
+ * since that is facts the caller already has, e.g. the block record or a diff stat).
+ *
+ * `buildQuestionPayload` is the one function callers actually need: it renders one or more
+ * registry entries into the `{<id>: {type, instructions, criteria}}` shape `askJev` sends,
+ * honouring two config hooks from `system1` (§1.3, §8.3):
+ *   - `system1.criteria_extra.<id>` — merges (never replaces) extra criteria labels into a
+ *     question, and may override `instructions` with a project-specific phrasing.
+ *   - `system1.disable` — a question id in this list is never sent to Jev at all;
+ *     `buildQuestionPayload` throws rather than silently rendering it, so a caller can't forget to
+ *     check `isQuestionDisabled` first and accidentally leak a diff hunk to Jev anyway.
+ */
+
+/**
+ * @typedef {object} QuestionSpec
+ * @property {'choice'|'score'|'noul'} type
+ * @property {string} fires - documentation: when this question is asked.
+ * @property {string} state - documentation: what `state` looks like for this question.
+ * @property {string} instructions
+ * @property {Record<string, string>} criteria
+ */
+
+/** @type {Readonly<Record<string, QuestionSpec>>} */
+export const QUESTIONS = Object.freeze({
+  lane: Object.freeze({
+    type: 'choice',
+    fires: 'plan: per block; code: on re-decomposition',
+    state: '{block:{task, owned_files, acceptance}, facts_excerpt}',
+    instructions: 'Which is the lowest model level that can reliably complete `block.task` within `block.owned_files`?',
+    criteria: Object.freeze({
+      L0: 'trivial',
+      L1: 'plain feature, following an existing pattern',
+      L2: 'hard (money, dates, tenancy, migrations, concurrency, unknown failure)',
+      split: 'the block is too large or mixes two concerns — re-decompose before dispatch',
+    }),
+  }),
+  risk: Object.freeze({
+    type: 'score',
+    fires: 'plan: per block; code: per finished file',
+    state: '{block or file, diff_stat, paths}',
+    instructions: 'How much damage could a subtle mistake here cause in production?',
+    criteria: Object.freeze({
+      0: 'cosmetic',
+      1: 'wrong behaviour, easy to notice and revert',
+      2: 'silent wrong data for some users',
+      3: 'silent wrong money or cross-tenant leak',
+    }),
+  }),
+  security_sensitive: Object.freeze({
+    type: 'noul',
+    fires: 'plan: per block; code: per file when path floors did not already force high',
+    state: '{paths, diff_stat, symbols_touched}',
+    instructions:
+      'Does this change touch authentication, authorization, tenancy boundaries, secrets, money movement or webhook verification?',
+    criteria: Object.freeze({ true: 'yes', false: 'no' }),
+  }),
+  next: Object.freeze({
+    type: 'choice',
+    fires: "code: after each attempt's tool gate",
+    state: '{evidence:{tests, lint, types, format, attempt, previous_attempts, new_tests_added, no_new_tests_reason, forecast_vs_actual}}',
+    instructions: 'Given `evidence` from deterministic checks after a coding attempt, what should the orchestrator do next?',
+    criteria: Object.freeze({
+      complete: 'all green, tests added or no_new_tests_reason given',
+      retry: 'contained failure the same coder can fix in one more attempt',
+      escalate: 'repeated or spreading failures, or risky area',
+      stop: 'the evidence contradicts the brief (wrong base, missing dependency, acceptance impossible)',
+    }),
+  }),
+  scope: Object.freeze({
+    type: 'noul',
+    fires: 'code: block gate, once, on the hunks outside the acceptance-named tests',
+    state: '{acceptance, owned_files, hunks_outside_named_tests}',
+    instructions: 'Do these hunks contain a change unrelated to `acceptance`?',
+    criteria: Object.freeze({ true: 'yes', false: 'no' }),
+  }),
+  defect: Object.freeze({
+    type: 'noul',
+    fires: 'review: per finding that has not passed a judge',
+    state: '{file_diff_hunk, finding}',
+    instructions: 'Is `finding` a real defect in `file_diff_hunk` that must be fixed before merge (not a style preference)?',
+    criteria: Object.freeze({ true: 'real correctness, safety or rule-violation defect', false: 'style, naming or preference only' }),
+  }),
+  resolved: Object.freeze({
+    type: 'noul',
+    fires: 'fix loop: per open finding after a fix',
+    state: '{finding, fix_hunk}',
+    instructions: 'Does `fix_hunk` resolve `finding` without introducing a new problem in the shown lines?',
+    criteria: Object.freeze({ true: 'yes', false: 'no' }),
+  }),
+});
+
+/** The 7 registered question ids, in table order. */
+export const QUESTION_IDS = Object.freeze(Object.keys(QUESTIONS));
+
+/**
+ * @param {string} id
+ * @returns {boolean}
+ */
+export function isKnownQuestion(id) {
+  return typeof id === 'string' && Object.hasOwn(QUESTIONS, id);
+}
+
+/**
+ * @param {string} id
+ * @param {Record<string, any>} [cfg]
+ * @returns {boolean} `true` when `system1.disable` lists `id` — this question must never be sent
+ *   to Jev (§8.3: "for projects that will not send diff hunks to Jev").
+ */
+export function isQuestionDisabled(id, cfg = {}) {
+  const disabled = cfg?.system1?.disable;
+  return Array.isArray(disabled) && disabled.includes(id);
+}
+
+/**
+ * Merge a question's shipped `criteria` with `system1.criteria_extra.<id>.criteria` (extra keys
+ * win on a collision — a project override is deliberate) and pick `instructions` (the extra one
+ * wins when given).
+ * @param {string} id
+ * @param {Record<string, any>} [cfg]
+ * @returns {{type: 'choice'|'score'|'noul', instructions: string, criteria: Record<string, string>}}
+ * @throws {TypeError} for an unknown id, or one `system1.disable` lists.
+ */
+export function renderQuestion(id, cfg = {}) {
+  if (!isKnownQuestion(id)) {
+    throw new TypeError(`renderQuestion: unknown question id ${JSON.stringify(id)}`);
+  }
+  if (isQuestionDisabled(id, cfg)) {
+    throw new TypeError(`renderQuestion: question ${JSON.stringify(id)} is disabled by system1.disable`);
+  }
+  const spec = QUESTIONS[id];
+  const extra = cfg?.system1?.criteria_extra?.[id] ?? {};
+  return {
+    type: spec.type,
+    instructions: typeof extra.instructions === 'string' && extra.instructions.length > 0 ? extra.instructions : spec.instructions,
+    criteria: { ...spec.criteria, ...(extra.criteria ?? {}) },
+  };
+}
+
+/**
+ * Render one or more question ids into the `{<id>: {type, instructions, criteria}}` shape
+ * `askJev`'s `questions` argument takes.
+ * @param {string[]} ids
+ * @param {Record<string, any>} [cfg]
+ * @returns {Record<string, {type: 'choice'|'score'|'noul', instructions: string, criteria: Record<string, string>}>}
+ */
+export function buildQuestionPayload(ids, cfg = {}) {
+  if (!Array.isArray(ids) || ids.length === 0) {
+    throw new TypeError('buildQuestionPayload: ids must be a non-empty array');
+  }
+  /** @type {Record<string, {type: 'choice'|'score'|'noul', instructions: string, criteria: Record<string, string>}>} */
+  const out = {};
+  for (const id of ids) {
+    out[id] = renderQuestion(id, cfg);
+  }
+  return out;
+}

package/src/decide/thresholds.mjs

@@ -0,0 +1,199 @@
+/**
+ * The S1 → S2 hand-off maths (plan §3.3, O8) — the ONE place that turns a raw Jev answer into
+ * `{confidence, margin}` and decides whether S1 acts, S2 checks, or S2 decides alone.
+ *
+ * **O8, verbatim:** `choice`/`score` — `confidence = p(top1)`, `margin = p(top1) − p(top2)`
+ * (`p(top2) = 0` when there is only one non-zero probability). `noul` — `answer = p ≥ 0.5`,
+ * `confidence = max(p, 1 − p)`, `margin = |2p − 1|`. This module NEVER reads an API-supplied
+ * `confidence`/`score` field for this purpose — it recomputes from `probabilities`/`noul` every
+ * time, so a provider that ever changes how it rounds its own `confidence` field cannot silently
+ * drift our thresholds. (A mutant that reads `p` as the confidence for a `noul` answer must turn
+ * `decide()` red on the documented `finding:nit` fixture — see `test/decide/probes.test.mjs`.)
+ *
+ * **Bands (§3.3):** `confidence ≥ act (0.90)` AND `margin ≥ close_margin (0.15)` ⇒ `'act'` (S1
+ * decides) · `check (0.60) ≤ confidence < act`, OR `confidence ≥ act` but `margin < close_margin`
+ * ⇒ `'check'` (S2 checks S1's answer) · `confidence < check` ⇒ `'decide'` (S2 decides from the
+ * state alone). Overridable per question via `thresholds.<id>`, falling back to
+ * `thresholds.default`, falling back to the defaults below — `validate.mjs`/the schema never
+ * apply these as JSON-Schema `default`s (no `ajv useDefaults` anywhere in this package), so this
+ * module is the one place they are real.
+ *
+ * **Findings keep their own bands** (`thresholds.findings`, §3.3 last sentence): a `defect`
+ * answer's raw `noul` PROBABILITY (not confidence) is banded `fix_now` (≥ 0.90) / `judge`
+ * (0.40–0.90) / `nit` (< 0.40); a `resolved` answer is `closed` (≥ 0.90) or `recheck` (else).
+ * These are a SEPARATE decision from `decide()`'s general act/check/decide bands — a review
+ * engine (B12) uses `bandFinding`/`bandResolved` to triage a finding's severity, not to decide
+ * whether S1 or S2 owns the call.
+ */
+
+/** §3.3's documented defaults — used whenever `thresholds.<id>`/`thresholds.default` omit a field. */
+export const DEFAULT_BAND = Object.freeze({ act: 0.9, check: 0.6, close_margin: 0.15 });
+
+/** §1.3's documented `thresholds.findings` defaults. */
+export const DEFAULT_FINDINGS = Object.freeze({ fix: 0.9, nit: 0.4, resolved: 0.9 });
+
+/**
+ * @typedef {import('./jev-client.mjs').JevAnswer} JevAnswer
+ * @typedef {{act: number, check: number, close_margin: number}} ThresholdBand
+ */
+
+/**
+ * @param {string} questionId
+ * @param {Record<string, any>} [cfg]
+ * @returns {ThresholdBand}
+ */
+export function bandsFor(questionId, cfg = {}) {
+  const perQuestion = cfg?.thresholds?.[questionId] ?? {};
+  const dflt = cfg?.thresholds?.default ?? {};
+  return {
+    act: perQuestion.act ?? dflt.act ?? DEFAULT_BAND.act,
+    check: perQuestion.check ?? dflt.check ?? DEFAULT_BAND.check,
+    close_margin: perQuestion.close_margin ?? dflt.close_margin ?? DEFAULT_BAND.close_margin,
+  };
+}
+
+/**
+ * @param {Record<string, any>} [cfg]
+ * @returns {{fix: number, nit: number, resolved: number}}
+ */
+export function findingsThresholds(cfg = {}) {
+  const raw = cfg?.thresholds?.findings ?? {};
+  return {
+    fix: raw.fix ?? DEFAULT_FINDINGS.fix,
+    nit: raw.nit ?? DEFAULT_FINDINGS.nit,
+    resolved: raw.resolved ?? DEFAULT_FINDINGS.resolved,
+  };
+}
+
+/**
+ * Sort a `probabilities` map's values descending. Tolerant of a single-key map (`p(top2) = 0`,
+ * O8's own worked example — a lane answer with only `L0: 1.0` set).
+ * @param {Record<string, number>} probabilities
+ * @returns {number[]}
+ */
+function sortedProbabilities(probabilities) {
+  if (probabilities === null || typeof probabilities !== 'object') {
+    throw new TypeError('sortedProbabilities: probabilities must be an object');
+  }
+  const values = Object.values(probabilities);
+  if (values.length === 0 || values.some((v) => typeof v !== 'number' || !Number.isFinite(v))) {
+    throw new TypeError('sortedProbabilities: probabilities must hold only finite numbers');
+  }
+  return [...values].sort((a, b) => b - a);
+}
+
+/**
+ * @param {Record<string, number>} probabilities
+ * @returns {string} the key whose value is the largest (first one, on a tie).
+ */
+function argmax(probabilities) {
+  let bestKey = null;
+  let bestValue = -Infinity;
+  for (const [key, value] of Object.entries(probabilities)) {
+    if (value > bestValue) {
+      bestValue = value;
+      bestKey = key;
+    }
+  }
+  return bestKey;
+}
+
+/**
+ * O8's confidence/margin maths, plus the decided VALUE (independent of the raw `choice`/`score`
+ * field the API also returned, for `choice` — the argmax of `probabilities` is authoritative here
+ * so confidence/margin and the reported value can never disagree with each other).
+ *
+ * `answer` is typed `any`, not the stricter {@link JevAnswer} union, deliberately: this is a
+ * boundary function for an external API's parsed JSON — TypeScript cannot verify a network
+ * response's shape at compile time regardless of the JSDoc typedef, and this function's entire
+ * job IS the runtime validation `JevAnswer` only documents. Every branch below still checks its
+ * own shape and throws a `TypeError` on anything that doesn't match.
+ * @param {any} answer
+ * @returns {{confidence: number, margin: number, value: string|number|boolean}}
+ */
+export function computeConfidenceMargin(answer) {
+  if (answer === null || typeof answer !== 'object') {
+    throw new TypeError('computeConfidenceMargin: answer must be an object');
+  }
+  if (answer.type === 'choice') {
+    const [top1, top2 = 0] = sortedProbabilities(answer.probabilities);
+    return { confidence: top1, margin: top1 - top2, value: argmax(answer.probabilities) };
+  }
+  if (answer.type === 'score') {
+    const [top1, top2 = 0] = sortedProbabilities(answer.probabilities);
+    if (typeof answer.score !== 'number' || !Number.isFinite(answer.score)) {
+      throw new TypeError('computeConfidenceMargin: a "score" answer must carry a finite score');
+    }
+    return { confidence: top1, margin: top1 - top2, value: answer.score };
+  }
+  if (answer.type === 'noul') {
+    if (typeof answer.noul !== 'number' || !Number.isFinite(answer.noul) || answer.noul < 0 || answer.noul > 1) {
+      throw new TypeError('computeConfidenceMargin: a "noul" answer must carry noul in [0, 1]');
+    }
+    const p = answer.noul;
+    return { confidence: Math.max(p, 1 - p), margin: Math.abs(2 * p - 1), value: p >= 0.5 };
+  }
+  throw new TypeError(`computeConfidenceMargin: unknown answer.type ${JSON.stringify(answer?.type)}`);
+}
+
+/**
+ * @typedef {object} Decision
+ * @property {boolean} decided - true only for the `'act'` stage.
+ * @property {'act'|'check'|'decide'} stage
+ * @property {string|number|boolean} value - the S1-computed answer, independent of `stage`.
+ * @property {number} confidence
+ * @property {number} margin
+ */
+
+/**
+ * The general act/check/decide band (§3.3) for one question's answer. Does NOT apply to
+ * `defect`/`resolved` FINDING triage — use `bandFinding`/`bandResolved` for those.
+ * @param {string} questionId
+ * @param {any} answer - see {@link computeConfidenceMargin} for why this isn't `JevAnswer`.
+ * @param {Record<string, any>} [cfg]
+ * @returns {Decision}
+ */
+export function decide(questionId, answer, cfg = {}) {
+  const { confidence, margin, value } = computeConfidenceMargin(answer);
+  const band = bandsFor(questionId, cfg);
+  /** @type {'act'|'check'|'decide'} */
+  let stage;
+  if (confidence >= band.act && margin >= band.close_margin) {
+    stage = 'act';
+  } else if (confidence >= band.check) {
+    stage = 'check';
+  } else {
+    stage = 'decide';
+  }
+  return { decided: stage === 'act', stage, value, confidence, margin };
+}
+
+/**
+ * Finding triage band for a `defect` answer's raw `noul` PROBABILITY (§3.3, §4.2 step 4).
+ * @param {number} p - `answer.noul`, the probability the finding is real (NOT a confidence).
+ * @param {Record<string, any>} [cfg]
+ * @returns {'fix_now'|'judge'|'nit'}
+ */
+export function bandFinding(p, cfg = {}) {
+  if (typeof p !== 'number' || !Number.isFinite(p) || p < 0 || p > 1) {
+    throw new TypeError('bandFinding: p must be a finite number in [0, 1]');
+  }
+  const t = findingsThresholds(cfg);
+  if (p >= t.fix) return 'fix_now';
+  if (p >= t.nit) return 'judge';
+  return 'nit';
+}
+
+/**
+ * Finding triage band for a `resolved` answer's raw `noul` probability (§3.3).
+ * @param {number} p
+ * @param {Record<string, any>} [cfg]
+ * @returns {'closed'|'recheck'}
+ */
+export function bandResolved(p, cfg = {}) {
+  if (typeof p !== 'number' || !Number.isFinite(p) || p < 0 || p > 1) {
+    throw new TypeError('bandResolved: p must be a finite number in [0, 1]');
+  }
+  const t = findingsThresholds(cfg);
+  return p >= t.resolved ? 'closed' : 'recheck';
+}

package/src/doctor/index.mjs

@@ -0,0 +1,105 @@
+/**
+ * `code-forge doctor` (plan §2.3; block B13b): every row, in print order. `--quick` = the three
+ * rows the skill's preflight needs (config, harness links, Jev key resolution); the full run adds
+ * the PATH/Solo/gate rows, the live Jev call, ledger, `tmp`, the provider CLI probes (presence,
+ * version, flags, one call per role builder, isolation, path deny, Codex rules), the worker
+ * start/stop, the signer key and the `signer: same-user boundary only` line.
+ */
+
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { cliNameForProvider } from '../engines/provider-cli.mjs';
+import { newRunId } from '../state/paths.mjs';
+import { runRoot } from '../util/tmp.mjs';
+import { checkCommands, checkConfig, checkJev, checkKeys, checkLedger, checkLinks, checkTmp } from './local.mjs';
+import { configuredProviders, pingRoles, probeCli, probeCodexRules, probeIsolation, probePathDeny } from './probes.mjs';
+import { row } from './rows.mjs';
+import { probeWorkerAndSigner, SIGNER_ROW } from './worker-probe.mjs';
+
+/** @typedef {import('./rows.mjs').Row} Row */
+
+/**
+ * @typedef {object} DoctorDeps
+ * @property {NodeJS.ProcessEnv} [env] - the env probes and spawned CLIs see (default `process.env`).
+ * @property {Partial<Record<'claude'|'codex'|'grok', string>>} [bins] - replaces each provider CLI (tests: fakes).
+ * @property {any} [store] - B2 key store (default: the production chain).
+ * @property {any} [opRead]
+ * @property {typeof import('../decide/jev-client.mjs').askJev} [askJev]
+ * @property {string} [canary] - the path-deny canary (tests).
+ */
+
+/** @param {Record<string, any> | null} cfg @returns {string} a new, private run root for the probes. */
+function doctorRoot(cfg) {
+  const root = typeof cfg?.tmp?.root === 'string' ? cfg.tmp.root : undefined;
+  return runRoot(`doctor-${process.pid}-${Date.now()}-${randomBytes(3).toString('hex')}`, { root });
+}
+
+/**
+ * @param {{cwd?: string, quick?: boolean, runRootDir?: string}} opts - `runRootDir`: the caller's
+ *   run root (the CLI adopts one); otherwise the doctor makes one and removes it afterwards.
+ * @param {DoctorDeps} [deps]
+ * @returns {Promise<Row[]>}
+ */
+export async function runDoctor(opts = {}, deps = {}) {
+  const env = deps.env ?? process.env;
+  const cwd = path.resolve(opts.cwd ?? process.cwd());
+  const checked = await checkConfig(cwd);
+  const cfg = checked.cfg;
+  const links = await checkLinks(env.HOME || os.homedir());
+  const keys = await checkKeys(cfg, { env, store: deps.store, opRead: deps.opRead });
+  /** @type {Row[]} */
+  const rows = [...checked.rows, ...links, ...keys.rows];
+  if (opts.quick) return rows;
+
+  if (cfg) {
+    rows.push(...(await checkCommands(cfg, env.PATH ?? '')));
+    rows.push(...(await checkJev(cfg, keys.key, { askJev: deps.askJev })));
+  }
+  rows.push(...(await checkLedger()));
+  rows.push(...checkTmp(cfg));
+  if (!cfg) {
+    rows.push(row('probes', 'FAIL', 'probes', 'skipped: no valid config'));
+    rows.push(SIGNER_ROW);
+    return rows;
+  }
+
+  const ownRoot = opts.runRootDir === undefined;
+  let runRootDir;
+  try {
+    runRootDir = opts.runRootDir ?? doctorRoot(cfg);
+  } catch (err) {
+    rows.push(row('probes', 'FAIL', 'probes', `no temp root (${err?.message ?? 'error'})`));
+    rows.push(SIGNER_ROW);
+    return rows;
+  }
+  const workDir = path.join(runRootDir, 'doctor');
+  mkdirSync(workDir, { recursive: true, mode: 0o700 });
+  try {
+    const ctx = { cfg, cwd, workDir, runRootDir, env, bins: deps.bins, canary: deps.canary };
+    const missing = new Set();
+    for (const provider of configuredProviders(cfg)) {
+      const cli = cliNameForProvider(provider);
+      if (!cli) {
+        rows.push(row(`cli.${provider}`, 'FAIL', provider, 'no CLI mapping for this provider'));
+        missing.add(provider);
+        continue;
+      }
+      const probed = await probeCli(ctx, cli);
+      rows.push(...probed.rows);
+      if (!probed.present) missing.add(provider);
+    }
+    rows.push(...(await pingRoles(ctx, missing)));
+    const reviewerProvider = cfg.levels?.L2?.provider ?? cfg.provider;
+    const coderProvider = cfg.levels?.L1?.provider ?? cfg.provider;
+    rows.push(...(missing.has(reviewerProvider) ? [row('isolation', 'FAIL', 'isolation', 'skipped (reviewer CLI missing)')] : await probeIsolation(ctx)));
+    rows.push(...(missing.has(coderProvider) ? [row('path-deny', 'WARN', 'path deny', 'skipped (coder CLI missing)')] : await probePathDeny(ctx)));
+    if (configuredProviders(cfg).includes('openai')) rows.push(...probeCodexRules(ctx));
+    rows.push(...(await probeWorkerAndSigner({ cfg, configFile: checked.file, workDir, runRootDir, env, runId: newRunId() })));
+  } finally {
+    if (ownRoot) rmSync(runRootDir, { recursive: true, force: true });
+    else rmSync(workDir, { recursive: true, force: true });
+  }
+  return rows;
+}