@codedology/code-forge 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -6,6 +6,26 @@ waits on a second real consumer (plan §10.4, Q17).
 
 ## [Unreleased]
 
+## [0.3.2] — 2026-10-01
+
+### Fixed
+
+- Jev: `score` questions (such as `risk`) send their criteria as a list indexed by score. Jev refused the keyed object
+  with 422, so `doctor`'s Jev check failed and every `risk` call silently fell back to rules.
+- Review: on a small diff (20 added lines or fewer), a clean pass (passed, no findings, every hunk acknowledged) needs
+  only 40 output tokens instead of `review.min_tokens_out`, so a correct short review of a tiny file is no longer
+  refused as `too_short`. Any finding, or a larger diff, keeps the full floor.
+
+## [0.3.1] — 2026-10-01
+
+### Fixed
+
+- Claude sessions: the `--json-schema` passed to the Claude CLI no longer carries the top-level `$schema` pointer, which
+  the CLI rejected ("no schema with key or ref"), so every Claude reviewer session failed at once and each review came
+  back unavailable. Validation still uses the full schema.
+- Grok sessions: the answer is read from Grok's `structuredOutput`/`text` envelope, so Grok reviewer, author and System
+  2 calls no longer fail schema validation (`invalid-output`).
+
 ## [0.3.0] — 2026-10-01
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codedology/code-forge",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Plan/harden/code/review orchestration CLI and Agent Skill for cross-model, parallel, evidence-gated feature delivery.",
   "repository": {
     "type": "git",

package/skill/scripts/forge

@@ -10,7 +10,7 @@
 #      copied install with no package next to it); `test/skill/shim.test.mjs` asserts the pin
 #      equals package.json's version.
 # The shim holds no logic of its own: every verb, flag and message is the CLI's.
-PINNED_VERSION="0.3.0"
+PINNED_VERSION="0.3.2"
 set -eu
 
 self="$0"

package/src/decide/jev-client.mjs

@@ -91,7 +91,7 @@ async function requestIdOf(response) {
  * @typedef {object} JevQuestionSpec
  * @property {'choice'|'score'|'noul'} type
  * @property {string} instructions
- * @property {Record<string, string>} criteria
+ * @property {Record<string, string> | string[]} criteria - a list (index = score) for `score`
  *
  * @typedef {object} JevSuccess
  * @property {true} ok

package/src/decide/questions.mjs

@@ -146,16 +146,29 @@ export function renderQuestion(id, cfg = {}) {
  * `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>}>}
+ * @returns {Record<string, {type: 'choice'|'score'|'noul', instructions: string, criteria: Record<string, 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>}>} */
+  /** @type {Record<string, {type: 'choice'|'score'|'noul', instructions: string, criteria: Record<string, string> | string[]}>} */
   const out = {};
   for (const id of ids) {
-    out[id] = renderQuestion(id, cfg);
+    out[id] = toWire(renderQuestion(id, cfg));
   }
   return out;
 }
+
+/**
+ * Jev's wire shape: a `score` question takes `criteria` as a LIST whose index is the score (an
+ * object keyed `0..n` is refused with 422 "Input should be a valid list"); `choice` and `noul`
+ * keep the keyed object. The answer's `legend`/`probabilities` come back keyed `"0".."n"`.
+ * @param {{type: 'choice'|'score'|'noul', instructions: string, criteria: Record<string, string>}} q
+ * @returns {{type: 'choice'|'score'|'noul', instructions: string, criteria: Record<string, string> | string[]}}
+ */
+function toWire(q) {
+  if (q.type !== 'score') return q;
+  const keys = Object.keys(q.criteria).sort((a, b) => Number(a) - Number(b));
+  return { ...q, criteria: keys.map((k) => q.criteria[k]) };
+}

package/src/engines/builders/claude.mjs

@@ -202,7 +202,7 @@ function buildClosedBookArgv(params) {
   argv.push('--no-session-persistence');
   if (systemPromptText !== undefined) argv.push('--system-prompt', systemPromptText);
   argv.push('--output-format', 'json');
-  if (schema !== undefined) argv.push('--json-schema', JSON.stringify(schema));
+  if (schema !== undefined) argv.push('--json-schema', JSON.stringify(stripSchemaMeta(schema)));
   if (maxBudgetUsd !== undefined) argv.push('--max-budget-usd', String(maxBudgetUsd));
   argv.push('--permission-mode', 'dontAsk');
   if (!isFacts) {
@@ -222,3 +222,16 @@ export function buildClaudeArgv(params) {
   assertBaseParams('buildClaudeArgv', params);
   return params.role === 'coder' ? buildCoderArgv(params) : buildClosedBookArgv(params);
 }
+
+/**
+ * The Claude CLI's `--json-schema` validator does not know the draft 2020-12 meta-schema and exits
+ * 1 on a top-level `$schema` naming it ("no schema with key or ref …"). The local Ajv2020 check
+ * keeps the full schema; only the copy handed to the CLI drops the meta-schema pointer.
+ * @param {unknown} schema
+ * @returns {unknown}
+ */
+function stripSchemaMeta(schema) {
+  if (schema === null || typeof schema !== 'object' || Array.isArray(schema) || !('$schema' in schema)) return schema;
+  const { $schema: _meta, ...rest } = /** @type {Record<string, unknown>} */ (schema);
+  return rest;
+}

package/src/review/engine.mjs

@@ -28,7 +28,7 @@ import { resolveLevel } from '../config/known-ids.mjs';
 import { fallbackRisk } from '../decide/fallback-rules.mjs';
 import { tierFor } from '../proof/tiers.mjs';
 import { assembleJudgePacket, assemblePacket, attachFiles, budgetFor, readFileDiff } from './packet.mjs';
-import { FINDING_SCHEMA, minTokensOut, validateReview } from './validate-review.mjs';
+import { FINDING_SCHEMA, minTokensOut, SMALL_DIFF_ADDED_LINES, validateReview } from './validate-review.mjs';
 import { assertRowPath } from '../worker/ticket.mjs';
 
 /**
@@ -167,11 +167,12 @@ export async function reviewFile(input, deps) {
   if (diff.diffText.trim().length === 0) return { status: 'no_change', approved: false, ...head, sessions: [] };
   mkdirSync(workDir, { recursive: true, mode: 0o700 });
   const min = minTokensOut(cfg);
+  const smallDiff = diff.plusCount <= SMALL_DIFF_ADDED_LINES;
 
   /** @param {SessionSpec} spec @param {{text: string, hunkHeaders: string[], tokensIn: number, contextMode: string | null}} packet */
   const run = async (spec, packet) => {
     /** @type {Record<string, any>} */
-    let summary = await runOne(spec, packet.text, packet, { deps, workDir, min, cfg });
+    let summary = await runOne(spec, packet.text, packet, { deps, workDir, min, smallDiff, cfg });
     const needs = summary.review?.needs_file;
     if (spec.role === 'reviewer' && summary.status === 'ok' && Array.isArray(needs) && needs.length > 0) {
       const paths = safeNeeds(needs);
@@ -182,7 +183,7 @@ export async function reviewFile(input, deps) {
         extra = null;
       }
       if (extra === null) return { ...summary, status: 'unavailable', reason: 'needs_file-refused', review: null };
-      summary = { ...(await runOne(spec, `${packet.text}${extra}`, packet, { deps, workDir, min, cfg })), needs_file_round: true };
+      summary = { ...(await runOne(spec, `${packet.text}${extra}`, packet, { deps, workDir, min, smallDiff, cfg })), needs_file_round: true };
     }
     return summary;
   };
@@ -206,7 +207,7 @@ export async function reviewFile(input, deps) {
   if (judgeSpec) {
     const bySlot = Object.fromEntries(done.map((s) => [s.slot, s.review]));
     const packet = assembleJudgePacket({ diff, reports: { A: bySlot.A, B: bySlot.B }, cfg });
-    final = await runOne(judgeSpec, packet.text, packet, { deps, workDir, min, cfg });
+    final = await runOne(judgeSpec, packet.text, packet, { deps, workDir, min, smallDiff, cfg });
     sessions.push(publicSummary(final));
     if (final.status !== 'ok') {
       await note(deps, { event: 'review.unavailable', reason: final.reason, lens: 'judge' });
@@ -222,9 +223,9 @@ export async function reviewFile(input, deps) {
  * One session: packet file (0600, removed after), spawn, stub guard.
  * @param {SessionSpec} spec @param {string} text
  * @param {{hunkHeaders: string[], tokensIn: number, contextMode: string | null}} packet
- * @param {{deps: ReviewDeps, workDir: string, min: number, cfg: Record<string, any>}} env
+ * @param {{deps: ReviewDeps, workDir: string, min: number, smallDiff?: boolean, cfg: Record<string, any>}} env
  */
-async function runOne(spec, text, packet, { deps, workDir, min }) {
+async function runOne(spec, text, packet, { deps, workDir, min, smallDiff = false }) {
   const promptPath = path.join(workDir, `${spec.lens}-${randomBytes(6).toString('hex')}.md`);
   const base = { lens: spec.lens, role: spec.role, level: spec.level, slot: spec.slot, context_mode: packet.contextMode, ctx_tokens_in: packet.tokensIn };
   writeFileSync(promptPath, text, { mode: 0o600 });
@@ -244,7 +245,7 @@ async function runOne(spec, text, packet, { deps, workDir, min }) {
   } finally {
     rmSync(promptPath, { force: true });
   }
-  const verdict = validateReview(res, { hunkHeaders: packet.hunkHeaders, minTokensOut: min });
+  const verdict = validateReview(res, { hunkHeaders: packet.hunkHeaders, minTokensOut: min, smallDiff });
   const meta = {
     ...base,
     provider: res?.provider ?? null,

package/src/review/validate-review.mjs

@@ -18,6 +18,15 @@ export const UNAVAILABLE_REASONS = Object.freeze(['exit', 'schema', 'hunks_misma
 
 export const DEFAULT_MIN_TOKENS_OUT = 120;
 
+/**
+ * A clean pass (`passed: true`, no findings, every hunk acknowledged) on a SMALL diff legitimately
+ * needs few words: a 3-line placeholder reviewed by GPT-6 Astra produced 108 tokens and was refused
+ * as `too_short`. For such answers the floor drops to this value; any finding keeps the full floor.
+ */
+export const CLEAN_PASS_MIN_TOKENS_OUT = 40;
+/** A diff with at most this many added lines is "small" for the clean-pass floor. */
+export const SMALL_DIFF_ADDED_LINES = 20;
+
 /** The source answer schema (compiled per provider by the spawner). */
 export const FINDING_SCHEMA = Object.freeze(JSON.parse(readFileSync(new URL('./finding.schema.json', import.meta.url), 'utf8')));
 
@@ -45,10 +54,10 @@ export function minTokensOut(cfg) {
 
 /**
  * @param {Record<string, any> | null | undefined} session - a `spawnSession` result.
- * @param {{hunkHeaders: ReadonlyArray<string>, minTokensOut?: number}} expect
+ * @param {{hunkHeaders: ReadonlyArray<string>, minTokensOut?: number, smallDiff?: boolean}} expect - `smallDiff` lowers the floor to `CLEAN_PASS_MIN_TOKENS_OUT` for a clean pass only
  * @returns {Verdict}
  */
-export function validateReview(session, { hunkHeaders, minTokensOut: min = DEFAULT_MIN_TOKENS_OUT }) {
+export function validateReview(session, { hunkHeaders, minTokensOut: min = DEFAULT_MIN_TOKENS_OUT, smallDiff = false }) {
   if (!session || typeof session !== 'object') return { ok: false, reason: 'exit', detail: 'no session result' };
   if (session.status === 'timeout') return { ok: false, reason: 'timeout', detail: 'killed at the session timeout' };
   const exitCode = session.exit_code;
@@ -65,6 +74,9 @@ export function validateReview(session, { hunkHeaders, minTokensOut: min = DEFAU
     return { ok: false, reason: 'hunks_mismatch', detail: `reviewed_hunks has ${got.length} entries; the packet has ${hunkHeaders.length} hunks` };
   }
   const tokensOut = Number(session.usage?.tokens_out ?? session.row?.tokens_out ?? 0);
-  if (!(tokensOut >= min)) return { ok: false, reason: 'too_short', detail: `tokens_out ${tokensOut} < ${min}` };
+  const review = /** @type {{passed: boolean, findings: unknown[]}} */ (session.answer);
+  const cleanPass = review.passed === true && Array.isArray(review.findings) && review.findings.length === 0;
+  const floor = smallDiff && cleanPass ? Math.min(min, CLEAN_PASS_MIN_TOKENS_OUT) : min;
+  if (!(tokensOut >= floor)) return { ok: false, reason: 'too_short', detail: `tokens_out ${tokensOut} < ${floor}` };
   return { ok: true, review: session.answer, tokens_out: tokensOut };
 }

package/src/session/spawn.mjs

@@ -177,8 +177,9 @@ export function readAnswer(cli, stdout, outText) {
     return { parsed: errorEvent ?? null, text, answer: tryJSON(text), usage: parseUsage('codex', usageEvent ?? null) };
   }
   const parsed = tryJSON(stdout.trim());
-  const text = typeof parsed?.result === 'string' ? parsed.result : stdout;
-  const answer = parsed?.structured_output ?? tryJSON(text);
+  // Claude's envelope carries `result` + `structured_output`; Grok's carries `text` + `structuredOutput`.
+  const text = typeof parsed?.result === 'string' ? parsed.result : typeof parsed?.text === 'string' ? parsed.text : stdout;
+  const answer = parsed?.structured_output ?? parsed?.structuredOutput ?? tryJSON(text);
   return { parsed: parsed ?? null, text, answer, usage: parseUsage(/** @type {"claude"|"grok"} */ (cli), parsed ?? null) };
 }