@codedology/code-forge 0.15.1 → 0.15.2

package/CHANGELOG.md

@@ -6,6 +6,12 @@ waits on a second real consumer (plan §10.4, Q17).
 
 ## [Unreleased]
 
+## [0.15.2] — 2026-10-30
+
+### Fixed
+
+- OpenAI strict schemas make only optional keys nullable, so `forge facts` no longer refuses an answer with null on a required field; a facts row with a null command or excerpt is downgraded to UNVERIFIABLE on its own (issue #27, B165)
+
 ## [0.15.1] — 2026-10-19
 
 ### Changed

package/README.md

@@ -2,7 +2,7 @@
 
 A CLI and Agent Skill for cross-model, parallel, evidence-gated feature delivery.
 
-Latest: 0.15.1 - see [CHANGELOG.md](CHANGELOG.md)
+Latest: 0.15.2 - see [CHANGELOG.md](CHANGELOG.md)
 
 ## The problem
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codedology/code-forge",
-  "version": "0.15.1",
+  "version": "0.15.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.15.1"
+PINNED_VERSION="0.15.2"
 set -eu
 
 self="$0"

package/src/config/schema-compile.mjs

@@ -4,7 +4,7 @@
  *
  * OpenAI's structured-output "strict" mode has three rules a hand-written schema violates by
  * default: (1) every property under an object must be listed in `required` (optional fields are
- * instead modeled as **nullable** required fields), (2) every object must set
+ * instead modeled as **nullable** required fields; source-required keys stay as they are), (2) every object must set
  * `additionalProperties: false`, (3) nothing may be missing from `required`. Claude and Grok take
  * the source schema unchanged (they support ordinary JSON Schema `required`/optional).
  *
@@ -149,8 +149,9 @@ function childSchemas(node) {
 }
 
 /**
- * Recursively rewrites every object node: a `properties` map makes every property `required` and
- * nullable and closes the node (unless it already has an open-ended `additionalProperties`); a
+ * Recursively rewrites every object node: a `properties` map makes every property `required`;
+ * optional keys become nullable; required keys stay as they are. It closes the node (unless it
+ * already has an open-ended `additionalProperties`); a
  * bare `{type: 'object'}` is closed to an empty strict object. `visited` guards against revisiting
  * the same shared node twice — not against a genuine schema cycle, which this project's schema
  * does not have.
@@ -165,12 +166,13 @@ function compileForOpenAI(node, visited) {
 
   if (node.properties && typeof node.properties === 'object') {
     const keys = Object.keys(node.properties);
+    const wasRequired = new Set(Array.isArray(node.required) ? node.required : []);
     node.required = keys;
     if (node.additionalProperties === undefined) {
       node.additionalProperties = false;
     }
     for (const key of keys) {
-      makeNullable(node.properties[key]);
+      if (!wasRequired.has(key)) makeNullable(node.properties[key]);
     }
   } else if (isObjectTyped(node) && node.additionalProperties === undefined && node.patternProperties === undefined) {
     node.properties = {};

package/src/session/facts.mjs

@@ -777,7 +777,8 @@ function ruleBroken(row, claim, ctx) {
 }
 
 /**
- * Validate the delegate's answer (step 3). Only a schema-invalid answer is refused. A row answers
+ * Validate the delegate's answer (step 3). Null commands/excerpts are normalized on a copy and
+ * their matched claims downgraded; every other schema-invalid answer is refused. A row answers
  * claim `F<n>` when its fact_id is `F<n>` and its kind is the claim's kind (the id is the anchor,
  * the claim text may be reworded); failing that, when its echoed claim ({@link echoedClaim})
  * equals the claim token and its fact_id is `F<n>` or its kind is the claim's kind. Claims the
@@ -794,11 +795,23 @@ function ruleBroken(row, claim, ctx) {
  * @throws {FactsError} `refused` when the answer does not match the schema.
  */
 export function validateFacts(answer, claims, opts = {}) {
-  if (!validateFile(answer)) {
+  const normalized = structuredClone(answer);
+  /** @type {Map<object, string[]>} */
+  const nullFields = new Map();
+  if (normalized && typeof normalized === 'object' && 'facts' in normalized && Array.isArray(normalized.facts)) {
+    for (const row of normalized.facts) {
+      if (!row || typeof row !== 'object' || Array.isArray(row)) continue;
+      const fields = ['command', 'output_excerpt'].filter((field) => row[field] === null);
+      if (fields.length === 0) continue;
+      for (const field of fields) row[field] = '';
+      nullFields.set(row, fields);
+    }
+  }
+  if (!validateFile(normalized)) {
     const where = (validateFile.errors ?? []).map((e) => `${e.instancePath || '/'} ${e.message}`).slice(0, 5);
     throw new FactsError('refused', `facts answer does not match facts.schema.json: ${where.join('; ')}`);
   }
-  const rows = /** @type {{facts: Fact[]}} */ (answer).facts;
+  const rows = /** @type {{facts: Fact[]}} */ (normalized).facts;
   /** @type {Fact[]} */
   const facts = [];
   /** @type {Downgrade[]} */
@@ -828,7 +841,8 @@ export function validateFacts(answer, claims, opts = {}) {
       return;
     }
     const base = { fact_id: id, claim: redact(claim.token), kind: claim.kind, command: redact(row.command), output_excerpt: claim.kind === 'env' ? '' : redact(row.output_excerpt) };
-    const broken = ruleBroken(row, claim, opts);
+    const fields = nullFields.get(row);
+    const broken = fields ? `delegate returned null ${fields.join(', ')}` : ruleBroken(row, claim, opts);
     if (broken) {
       const reason = redact(broken);
       downgraded.push({ fact_id: id, reason });