V48 Gate 3 (implementation-only): stitch repairs carry the validation error; the schema shape hint renders every field

Root-caused from the raw LLM I/O sidecar of the two deposit runs that died
on 'StitchUntilComplete exceeded maximum stitch attempts (5)' (runs
ea150f3e/02b93ba8, 2026-07-01): every option the model produced omitted
'confidence' — the structured-output shape hint truncated nested objects to
their first six fields, so the model never saw confidence/patch/
needinessSignal in the schema hint, and the stitch instruction ('Continue
and complete the previous output') never said what failed validation, so
five stitch cycles reproduced the same omission until the step threw.

- inferField now renders EVERY nested field of a ZodObject (no slice(0,6)
  ellipsis hiding required fields).
- factoryStitchUntilComplete captures the last schema-validation error and
  prompts the repair with it, instead of a truncation-only 'continue'.

Regression-pinned in stitch-self-repair-and-schema-shape.test.ts against
the deposit candidateSetSchema shape. agent-generics 23 tests green; tsc
clean; asset-pack 227 green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: geraldarthurdavis

packages/agent-generics/src/__tests__/stitch-self-repair-and-schema-shape.test.ts

@@ -0,0 +1,62 @@
+// @ts-nocheck
+import { z } from 'zod';
+import { Execution } from '@bitcode/execution-generics';
+import { factoryStitchUntilComplete, factoryStructuredOutput } from '../substeps/factories';
+
+describe('StitchUntilComplete self-repair instruction', () => {
+  it('tells the model exactly what failed schema validation instead of only "continue"', async () => {
+    const schema = z.object({ value: z.string(), confidence: z.number() });
+    const stitchInputs: any[] = [];
+    const gen = async (input: any) => {
+      stitchInputs.push(input);
+      return { value: 'x', confidence: 0.9 };
+    };
+    const stitch = factoryStitchUntilComplete([gen], schema);
+    const result = await stitch({ value: 'x' }, new Execution('root'));
+
+    expect(stitchInputs).toHaveLength(1);
+    expect(stitchInputs[0].instruction).toContain('failed schema validation');
+    expect(stitchInputs[0].instruction).toContain('confidence');
+    expect(result.finalOutput).toEqual({ value: 'x', confidence: 0.9 });
+  });
+});
+
+describe('structured output schema shape rendering', () => {
+  it('renders every nested field — required fields beyond the sixth must reach the model', async () => {
+    // Mirrors the deposit candidateSetSchema shape whose 7th..9th fields
+    // (confidence, patch, needinessSignal) were hidden by the truncated hint.
+    const candidate = z.object({
+      kind: z.string(),
+      title: z.string(),
+      summary: z.string(),
+      coveredSourcePaths: z.array(z.string()),
+      measurements: z.record(z.string(), z.number()),
+      measurementRationale: z.string(),
+      confidence: z.number(),
+      patch: z.object({ fileChanges: z.array(z.object({ path: z.string(), op: z.enum(['create', 'modify', 'delete']) })), patchSummary: z.string() }),
+      needinessSignal: z.object({ demand: z.number(), saturation: z.number(), rationale: z.string() }).optional(),
+    });
+    const schema = z.object({ options: z.array(candidate) });
+
+    let capturedUserPrompt = '';
+    const exec = new Execution('root') as any;
+    exec.llms = {
+      getDefaultLLM: () => async (llmInput: any) => {
+        const user = (llmInput.messages || []).find((m: any) => m.role === 'user');
+        capturedUserPrompt = user?.content ?? '';
+        return {
+          content: JSON.stringify({ options: [] }),
+          usage: { totalTokens: 5 },
+          metadata: { provider: 'test', model: 'test-model' },
+        };
+      },
+    };
+
+    const structured = factoryStructuredOutput(schema);
+    await structured({ context: 'synthesize' }, exec);
+
+    for (const field of ['kind', 'title', 'summary', 'coveredSourcePaths', 'measurements', 'measurementRationale', 'confidence', 'patch', 'needinessSignal']) {
+      expect(capturedUserPrompt).toContain(`"${field}"`);
+    }
+  });
+});

packages/agent-generics/src/substeps/factories.ts

@@ -561,6 +561,10 @@ export function factoryStitchUntilComplete<T>(
     let currentResult = input;
     let stitchCount = 0;
     const maxStitches = 5; // Prevent infinite loops
+    // The most recent schema-validation failure. A stitch prompted only with
+    // "continue" cannot repair a schema gap (e.g. a field the model never
+    // emits) — the model must be told exactly what failed validation.
+    let lastValidationError: string | undefined;
 
     // Check if output appears truncated (measure the structured output if present)
     const checkTruncation = (candidate: any): boolean => {
@@ -583,8 +587,9 @@ export function factoryStitchUntilComplete<T>(
             : currentResult;
           outputSchema.parse(candidate);
           break; // Valid complete output; no stitching required
-        } catch {
+        } catch (e) {
           // Fall through to truncation/stitching logic
+          lastValidationError = e instanceof Error ? e.message : String(e);
         }
       }
 
@@ -599,11 +604,8 @@ export function factoryStitchUntilComplete<T>(
             break; // Valid complete output
           } catch (e) {
             // Output incomplete, needs stitching
-            failsafeExec.store(
-              'validation',
-              'error',
-              e instanceof Error ? e.message : String(e)
-            );
+            lastValidationError = e instanceof Error ? e.message : String(e);
+            failsafeExec.store('validation', 'error', lastValidationError);
           }
         } else {
           break; // No schema to validate against
@@ -618,7 +620,10 @@ export function factoryStitchUntilComplete<T>(
       const stitchInput = {
         context: buildStitchContext(input),
         partialOutput: minimalPartial,
-        instruction: 'Continue and complete the previous output'
+        instruction: lastValidationError
+          ? `The previous output failed schema validation: ${lastValidationError.slice(0, 600)}. ` +
+            'Return the full corrected JSON object with every required field present and within its constraints.'
+          : 'Continue and complete the previous output'
       } as any;
 
       for (let i = 0; i < generationSubSteps.length; i++) {
@@ -830,8 +835,11 @@ function inferField(v: z.ZodTypeAny): string {
     case z.ZodFirstPartyTypeKind.ZodObject: {
       const shape = getZodObjectShape(v);
       if (!shape) return '{ ... }';
-      const keys = Object.entries(shape).slice(0, 6);
-      return `{ ${keys.map(([key, value]) => `"${key}": ${inferField(value)}`).join(', ')}${Object.keys(shape).length > keys.length ? ', ...' : ''} }`;
+      // Render EVERY field: a truncated shape hides required fields from the
+      // model, which then systematically omits them and no amount of
+      // stitching/retrying can converge on a schema-valid output.
+      const keys = Object.entries(shape);
+      return `{ ${keys.map(([key, value]) => `"${key}": ${inferField(value)}`).join(', ')} }`;
     }
     case z.ZodFirstPartyTypeKind.ZodRecord: return '{ [key: string]: any }';
     case z.ZodFirstPartyTypeKind.ZodEnum: {