V48 Gate 3 (impl-only): Visible Setup/Validation gates

geraldarthurdavis · geraldarthurdavis · commit 51f8aeede010 · 2026-07-19T19:00:30.000-07:00
Stamp finalApproval on deposit/read readyToFinish so DIV admits Finish
and UI stops painting ITERATE (FINISH). Emit formal phase-decision rows
when Setup host-env clone or Validation deterministic gate skips PTRR.
diff --git a/apps/uapi/components/bitcode/pipeline/models/pipeline-run-activity.ts b/apps/uapi/components/bitcode/pipeline/models/pipeline-run-activity.ts
@@ -255,7 +255,27 @@ function iterationForPhase(
     : null;
 }
 
-type FormalLogLineKind = 'llm' | 'tool';
+type FormalLogLineKind = 'llm' | 'tool' | 'decision';
+
+function isPhaseDecisionPayload(payload: any, ns: string, key: string): boolean {
+  const data = payload?.data;
+  if (data && typeof data === 'object' && !Array.isArray(data)) {
+    if ((data as { formalPhaseDecision?: unknown }).formalPhaseDecision === true) {
+      return true;
+    }
+    if (
+      typeof (data as { schema?: unknown }).schema === 'string' &&
+      String((data as { schema: string }).schema).includes('phase-decision')
+    ) {
+      return true;
+    }
+  }
+  // Product gate + short-circuit decision stores (Setup/Validation/Finish).
+  if (key === 'phaseDecision') return true;
+  if (ns === 'validation' && key === 'readyToFinish') return true;
+  if (ns === 'setup' && (key === 'phaseDecision' || key === 'cloneDecision')) return true;
+  return false;
+}
 
 function classifyFormalLogLine(payload: any): FormalLogLineKind | null {
   const type = String(payload?.type || '');
@@ -264,12 +284,13 @@ function classifyFormalLogLine(payload: any): FormalLogLineKind | null {
   const ns = String(payload?.namespace || '');
   const key = String(payload?.key || '');
 
-  // The rich telemetry renders ONLY the ultimate LLM-call layer and Tool uses —
-  // each with its complete hierarchy (LLM: Phase/Agent/Step/Failsafe/Thinkings;
-  // Tool: Phase/Agent/Step + tool). Everything else (informational status, phase
-  // banners, completion/error notices) advances the rolling context but never
-  // becomes a row; run completion is surfaced by the processing indicator and
-  // errors by the log's error banner, not by accordion rows.
+  // Formal rows:
+  //   • LLM call  — Thinkings substep output (full hierarchy)
+  //   • Tool use  — tool result/error
+  //   • Decision  — phase gate / short-circuit agent completion when no LLM/tool
+  //     fired (Setup host-env clone, Validation deterministic ready-to-finish).
+  // Product law: Setup and Validation must remain visible even when conditionals
+  // skip PTRR agents.
 
   // Formal LLM call: the Thinkings substep output is canonical (full hierarchy).
   if (type === 'generation' || streamType === 'generation') return 'llm';
@@ -279,6 +300,9 @@ function classifyFormalLogLine(payload: any): FormalLogLineKind | null {
   if (type === 'tool-use' || streamType === 'tool-use') return 'tool';
   if ((ns === 'tool' || ns === 'tools') && (key === 'result' || key === 'error')) return 'tool';
 
+  // Formal phase decision (deterministic short-circuit / gate).
+  if (isPhaseDecisionPayload(payload, ns, key)) return 'decision';
+
   return null;
 }
 
@@ -458,15 +482,33 @@ export function buildPipelineRunActivityFromEvents(
       !(payload.data as Record<string, unknown>).contentWithheld
     ) {
       const verdict = payload.data as Record<string, any>;
+      const recommendation =
+        typeof verdict.recommendation === 'string' ? verdict.recommendation : null;
+      // Normalize deposit admit: recommendation finish/complete ⇒ finalApproval.
+      const finalApproval =
+        typeof verdict.finalApproval === 'boolean'
+          ? verdict.finalApproval
+          : verdict.readyToFinish === true ||
+              verdict.ready === true ||
+              verdict.passed === true ||
+              String(recommendation || '').toLowerCase() === 'finish' ||
+              String(recommendation || '').toLowerCase() === 'complete'
+            ? true
+            : typeof verdict.finalApproval === 'boolean'
+              ? verdict.finalApproval
+              : null;
       readyToFinishVerdicts.push({
         iteration: rollingContext.iteration ?? null,
-        finalApproval: typeof verdict.finalApproval === 'boolean' ? verdict.finalApproval : null,
-        recommendation: typeof verdict.recommendation === 'string' ? verdict.recommendation : null,
+        finalApproval,
+        recommendation,
         qualityScore: typeof verdict.qualityScore === 'number' ? verdict.qualityScore : null,
         overallConfidence:
           typeof verdict.overallConfidence === 'number' ? verdict.overallConfidence : null,
         warningsCount: Array.isArray(verdict.finalWarnings) ? verdict.finalWarnings.length : 0,
-        reasons: inferReadyToFinishReasons(verdict),
+        reasons: inferReadyToFinishReasons({
+          ...verdict,
+          finalApproval: finalApproval === true,
+        }),
         summary: typeof verdict.summary === 'string' ? verdict.summary : null,
       });
     }
@@ -538,6 +580,51 @@ export function buildPipelineRunActivityFromEvents(
       continue;
     }
 
+    if (kind === 'decision') {
+      // Deterministic Setup/Validation/Finish decisions (no LLM/tool). Surface
+      // as a generation-shaped row so existing pill rendering applies.
+      const data =
+        payload?.data && typeof payload.data === 'object' && !Array.isArray(payload.data)
+          ? (payload.data as Record<string, unknown>)
+          : {};
+      const own = readEventExecutionState(payload);
+      const phase = String(
+        data.phase || own.phase || rollingContext.phase || ns || 'setup',
+      );
+      const merged: ExecContext = {
+        phase,
+        agent: String(
+          data.agent || own.agent || rollingContext.agent || key || 'phase-decision',
+        ),
+        step: String(data.step || own.step || rollingContext.step || 'decide'),
+        failsafe: String(
+          data.failsafe || own.failsafe || 'deterministic-gate',
+        ),
+        generation: String(data.generation || own.generation || 'structure'),
+        iteration: iterationForPhase(phase, rollingContext.iteration),
+      };
+      const text = String(
+        data.summary ||
+          data.message ||
+          payload?.message ||
+          payload?.status?.message ||
+          'Phase decision recorded.',
+      );
+      // Advance rolling hierarchy so later rows inherit Validation/Setup.
+      rollingContext.phase = merged.phase;
+      rollingContext.agent = merged.agent;
+      rollingContext.step = merged.step;
+      pushRow(
+        text,
+        stampExecutionState(
+          merged,
+          { ...payload, type: 'generation', message: text },
+          { phaseDecision: true },
+        ),
+      );
+      continue;
+    }
+
     if (kind === 'tool') {
       const acc = toolByNode.get(nodeId) || {};
       const toolName = resolvedToolName || (key === 'error' ? 'tool (failed)' : 'tool');
diff --git a/apps/uapi/components/deposits/DepositSynthesisTelemetry/DepositSynthesisTelemetry.tsx b/apps/uapi/components/deposits/DepositSynthesisTelemetry/DepositSynthesisTelemetry.tsx
@@ -173,7 +173,14 @@ export function DepositSynthesisTelemetry({
                     const verdicts = synthesisActivity.readyToFinishVerdicts;
                     const latest = verdicts[verdicts.length - 1];
                     const prior = verdicts.slice(0, -1);
-                    const approved = latest.finalApproval === true;
+                    // Deposit gate may stamp recommendation:'finish' without
+                    // finalApproval on older runs — treat both as admit.
+                    const approved =
+                      latest.finalApproval === true ||
+                      String(latest.recommendation || "").toLowerCase() ===
+                        "finish" ||
+                      String(latest.recommendation || "").toLowerCase() ===
+                        "complete";
                     return (
                       <div
                         data-testid="deposit-telemetry-readiness-verdict"
diff --git a/apps/uapi/tests/pipelineExecutionLogTelemetryUx.test.tsx b/apps/uapi/tests/pipelineExecutionLogTelemetryUx.test.tsx
@@ -262,6 +262,58 @@ describe('buildPipelineRunActivityFromEvents — mode latch + latest context', (
     expect(snapshot.latestContext).toBeNull();
   });
 
+  it('surfaces Setup/Validation phase decisions as formal rows (no LLM/tool)', () => {
+    const phaseEvents = [
+      {
+        id: 'setup-decision',
+        event: {
+          type: 'status',
+          namespace: 'setup',
+          key: 'phaseDecision',
+          data: {
+            formalPhaseDecision: true,
+            phase: 'setup',
+            agent: 'clone-vcs-repository',
+            step: 'decide',
+            failsafe: 'host-env-clone',
+            generation: 'structure',
+            summary:
+              'Setup clone complete (setup-in-box-branch-shallow): working tree ready at revision for this run.',
+            message:
+              'Setup clone complete (setup-in-box-branch-shallow): working tree ready at revision for this run.',
+          },
+        },
+        created_at: '2026-07-01T00:00:01.000Z',
+      },
+      {
+        id: 'validation-ready',
+        event: {
+          type: 'status',
+          namespace: 'validation',
+          key: 'readyToFinish',
+          data: {
+            formalPhaseDecision: true,
+            finalApproval: true,
+            recommendation: 'finish',
+            summary: 'Deposit synthesis ready to finish.',
+            message: 'Deposit synthesis ready to finish.',
+            phase: 'validation',
+            agent: 'ready-to-finish-asset-packs-synthesis-deposit-pipeline',
+            step: 'decide',
+          },
+        },
+        created_at: '2026-07-01T00:00:10.000Z',
+      },
+    ];
+    const snapshot = buildPipelineRunActivityFromEvents(phaseEvents, null, [], null);
+    const texts = Object.keys(snapshot.outputDetails);
+    expect(texts.some((t) => /Setup clone complete/i.test(t))).toBe(true);
+    expect(texts.some((t) => /ready to finish/i.test(t))).toBe(true);
+    expect(snapshot.readyToFinishVerdicts).toHaveLength(1);
+    expect(snapshot.readyToFinishVerdicts[0].finalApproval).toBe(true);
+    expect(snapshot.readyToFinishVerdicts[0].recommendation).toBe('finish');
+  });
+
   it('de-dupes formal rows that arrive twice (sandbox legacy + host bridge)', () => {
     const duped = [
       ...events,
diff --git a/packages/asset-packs-pipelines/syntheses/deposit/src/__tests__/deposit-ready-to-finish-agent.test.ts b/packages/asset-packs-pipelines/syntheses/deposit/src/__tests__/deposit-ready-to-finish-agent.test.ts
@@ -115,7 +115,17 @@ describe('deposit-ready-to-finish-agent', () => {
     const out = await runReady({}, exec);
     expect(Array.isArray(out.options?.[0]?.absolutes)).toBe(true);
     expect(out.options[0].absolutes.length).toBeGreaterThan(0);
-    expect(exec.get('validation', 'readyToFinish')).toBeTruthy();
+    expect(out.readyToFinish).toBe(true);
+    expect(out.finalApproval).toBe(true);
+    expect(exec.get('validation', 'readyToFinish')).toMatchObject({
+      finalApproval: true,
+      recommendation: 'finish',
+      formalPhaseDecision: true,
+    });
+    expect(exec.get('validation', 'phaseDecision')).toMatchObject({
+      phase: 'validation',
+      formalPhaseDecision: true,
+    });
   });
 
   it('flags obfuscation path violations', async () => {
diff --git a/packages/asset-packs-pipelines/syntheses/deposit/src/agents/finish/deposit-finish-synthesize-run-agent.ts b/packages/asset-packs-pipelines/syntheses/deposit/src/agents/finish/deposit-finish-synthesize-run-agent.ts
@@ -56,7 +56,13 @@ export default async function runDepositFinishSynthesizeRunAgent(input: any, exe
       },
       selectable: true,
     })),
-    readyToPresent: Boolean(ready?.recommendation === 'finish' || ready?.readyToFinish !== false),
+    readyToPresent: Boolean(
+      ready?.finalApproval === true ||
+        ready?.readyToFinish === true ||
+        ready?.ready === true ||
+        ready?.recommendation === 'finish' ||
+        ready?.recommendation === 'complete',
+    ),
     validationSummary: ready?.summary ?? null,
   };
 
@@ -101,9 +107,25 @@ export default async function runDepositFinishSynthesizeRunAgent(input: any, exe
 
   storeCrossPhaseArtifact(execution, 'finish', 'completion', completion);
   storeCrossPhaseArtifact(execution, 'finish', 'selectionEnvelope', selectionEnvelope);
+  const finishMessage = `Synthesize deposit AssetPacks finished with ${selectionEnvelope.options.length} option(s) for selection.`;
   storeCrossPhaseArtifact(execution, 'finish', 'summary', {
     optionCount: selectionEnvelope.options.length,
-    message: `Synthesize deposit AssetPacks finished with ${selectionEnvelope.options.length} option(s) for selection.`,
+    message: finishMessage,
+  });
+  // Formal Finish phase decision so the log always shows Finish closed even when
+  // Finish agents are mostly deterministic packaging (no long LLM trail).
+  storeCrossPhaseArtifact(execution, 'finish', 'phaseDecision', {
+    schema: 'bitcode.pipeline.phase-decision',
+    formalPhaseDecision: true,
+    phase: 'finish',
+    agent: 'finish-synthesize-asset-packs-for-deposit-run',
+    step: 'decide',
+    failsafe: 'selection-envelope',
+    generation: 'structure',
+    summary: finishMessage,
+    message: finishMessage,
+    optionCount: selectionEnvelope.options.length,
+    readyToPresent: selectionEnvelope.readyToPresent,
   });
 
   return {
diff --git a/packages/asset-packs-pipelines/syntheses/deposit/src/agents/validation/deposit-ready-to-finish-agent.ts b/packages/asset-packs-pipelines/syntheses/deposit/src/agents/validation/deposit-ready-to-finish-agent.ts
@@ -377,21 +377,51 @@ export default async function runDepositReadyToFinishAgent(input: any, execution
           : merged.recommendation
         : merged.recommendation;
 
+  const readyToFinish =
+    recommendation === 'complete' && hardIssues.length === 0;
   const result = {
     ...merged,
     issues: structureReady ? hardIssues : filteredMergedIssues,
     recommendation,
-    readyToFinish: recommendation === 'complete' && hardIssues.length === 0,
+    readyToFinish,
+    // SDIVF DIV gate + deposit telemetry require finalApproval (not only
+    // recommendation:'finish'). Without this, UI paints ITERATE (FINISH) and
+    // the base loop never sees validation:readyToFinish.finalApproval.
+    finalApproval: readyToFinish,
+    ready: readyToFinish,
+    passed: readyToFinish,
   };
 
+  const readinessSummary = readyToFinish
+    ? qualitativePtrrRan
+      ? 'Deposit synthesis ready to finish.'
+      : 'Deposit synthesis ready to finish (Validation deterministic admit: measured options + required absolutes; qualitative PTRR skipped).'
+    : `Deposit synthesis not ready: ${result.issues.slice(0, 5).join('; ')}`;
+
   storeCrossPhaseArtifact(execution, 'validation/implementation', 'issues', result.issues);
   storeCrossPhaseArtifact(execution, 'validation', 'depositQuality', result);
+  // Cross-phase gate artifact — dual-written to stream; UI treats as formal
+  // phase decision when no qualitative PTRR rows exist (F19 extension).
   storeCrossPhaseArtifact(execution, 'validation', 'readyToFinish', {
-    recommendation: result.readyToFinish ? 'finish' : 'revise',
-    summary: result.readyToFinish
-      ? 'Deposit synthesis ready to finish.'
-      : `Deposit synthesis not ready: ${result.issues.slice(0, 5).join('; ')}`,
+    schema: 'bitcode.deposit.validation.ready-to-finish',
+    recommendation: readyToFinish ? 'finish' : 'revise',
+    finalApproval: readyToFinish,
+    ready: readyToFinish,
+    passed: readyToFinish,
+    readyToFinish,
+    summary: readinessSummary,
+    message: readinessSummary,
     issues: result.issues,
+    qualityScore: result.qualityScore ?? agentOutput?.qualityScore ?? null,
+    // Hierarchy for formal telemetry row when PTRR was skipped.
+    phase: 'validation',
+    agent: 'ready-to-finish-asset-packs-synthesis-deposit-pipeline',
+    step: qualitativePtrrRan ? 'try' : 'decide',
+    failsafe: qualitativePtrrRan ? 'prepare' : 'deterministic-gate',
+    generation: qualitativePtrrRan ? 'reason' : 'structure',
+    formalPhaseDecision: true,
+    qualitativePtrrRan,
+    qualitativePtrrSkipped: !qualitativePtrrRan && structureReady,
   });
   // Always record whether qualitative PTRR ran or was short-circuited (every run).
   storeCrossPhaseArtifact(execution, 'validation', 'gateDecision', {
@@ -411,8 +441,24 @@ export default async function runDepositReadyToFinishAgent(input: any, execution
     qualitativePtrrError,
     recommendation: result.recommendation,
     readyToFinish: result.readyToFinish,
+    finalApproval: readyToFinish,
     qualityScore: result.qualityScore ?? agentOutput?.qualityScore ?? null,
   });
+  // Explicit phase-decision store so Setup/Validation short-circuits always
+  // produce a formal telemetry row even when no LLM/tool fire.
+  storeCrossPhaseArtifact(execution, 'validation', 'phaseDecision', {
+    schema: 'bitcode.pipeline.phase-decision',
+    formalPhaseDecision: true,
+    phase: 'validation',
+    agent: 'ready-to-finish-asset-packs-synthesis-deposit-pipeline',
+    step: qualitativePtrrRan ? 'try' : 'decide',
+    failsafe: qualitativePtrrRan ? 'prepare' : 'deterministic-gate',
+    generation: 'structure',
+    summary: readinessSummary,
+    message: readinessSummary,
+    finalApproval: readyToFinish,
+    recommendation: readyToFinish ? 'finish' : 'revise',
+  });
   storeCrossPhaseArtifact(execution, 'implementation', 'options', packs);
   storeCrossPhaseArtifact(execution, 'implementation', 'assetPacks', packs);
 
diff --git a/packages/asset-packs-pipelines/syntheses/domain/src/agents/setup/asset-pack-clone-vcs-repository-agent.ts b/packages/asset-packs-pipelines/syntheses/domain/src/agents/setup/asset-pack-clone-vcs-repository-agent.ts
diff --git a/packages/asset-packs-pipelines/syntheses/read/src/agents/validation/read-ready-to-finish-agent.ts b/packages/asset-packs-pipelines/syntheses/read/src/agents/validation/read-ready-to-finish-agent.ts
diff --git a/packages/generic-pipelines/execution-pipeline-sdivf/src/execution-pipeline-sdivf-factory.ts b/packages/generic-pipelines/execution-pipeline-sdivf/src/execution-pipeline-sdivf-factory.ts
