oh-my-codex 0.18.0 → 0.18.2

package/dist/pipeline/__tests__/stages.test.js

@@ -5,10 +5,13 @@ import { mkdtemp, rm, mkdir, readFile, writeFile } from 'fs/promises';
 import { basename, dirname, join, relative } from 'path';
 import { tmpdir } from 'os';
 import { existsSync } from 'fs';
+import { createDeepInterviewStage, buildDeepInterviewInstruction } from '../stages/deep-interview.js';
 import { createRalplanStage } from '../stages/ralplan.js';
 import { createTeamExecStage, buildTeamInstruction } from '../stages/team-exec.js';
 import { createRalphVerifyStage, createRalphStage, buildRalphInstruction } from '../stages/ralph-verify.js';
 import { createCodeReviewStage, buildCodeReviewInstruction } from '../stages/code-review.js';
+import { createUltragoalStage, buildUltragoalInstruction } from '../stages/ultragoal.js';
+import { createUltraqaStage, buildUltraqaInstruction } from '../stages/ultraqa.js';
 import { buildFollowupStaffingPlan } from '../../team/followup-planner.js';
 import { packageRoot } from '../../utils/paths.js';
 // ---------------------------------------------------------------------------
@@ -94,12 +97,13 @@ describe('RALPLAN Stage', () => {
         const stage = createRalplanStage();
         assert.equal(stage.name, 'ralplan');
     });
-    it('runs successfully and produces artifacts', async () => {
+    it('fails closed without planning artifacts and consensus evidence', async () => {
         const stage = createRalplanStage();
         const result = await stage.run(makeCtx());
-        assert.equal(result.status, 'completed');
+        assert.equal(result.status, 'failed');
         assert.equal(result.artifacts.stage, 'ralplan');
         assert.ok(result.artifacts.instruction);
+        assert.equal(result.error, 'ralplan_planning_artifacts_missing');
     });
     it('canSkip returns false when no plans directory exists', () => {
         const stage = createRalplanStage();
@@ -118,13 +122,329 @@ describe('RALPLAN Stage', () => {
         const stage = createRalplanStage();
         assert.equal(stage.canSkip(makeCtx()), false);
     });
-    it('canSkip returns true when both prd and test spec plan files exist', async () => {
+    it('canSkip returns false when only prd and test spec plan files exist without consensus evidence', async () => {
+        const plansDir = join(tempDir, '.omx', 'plans');
+        await mkdir(plansDir, { recursive: true });
+        await writeFile(join(plansDir, 'prd-my-feature.md'), '# Plan\n');
+        await writeFile(join(plansDir, 'test-spec-my-feature.md'), '# Test Spec\n');
+        const stage = createRalplanStage();
+        assert.equal(stage.canSkip(makeCtx()), false);
+    });
+    it('run fails with consensus-specific artifact error when consensus exists but planning artifacts are missing', async () => {
+        const stage = createRalplanStage();
+        const result = await stage.run(makeCtx({
+            artifacts: {
+                ralplan: {
+                    ralplanConsensusGate: {
+                        complete: true,
+                        sequence: ['architect-review', 'critic-review'],
+                        ralplan_architect_review: { agent_role: 'architect', verdict: 'approve' },
+                        ralplan_critic_review: { agent_role: 'critic', verdict: 'approve' },
+                    },
+                },
+            },
+        }));
+        assert.equal(result.status, 'failed');
+        assert.equal(result.error, 'ralplan_planning_artifacts_missing_after_consensus');
+        assert.equal(result.artifacts.planningComplete, false);
+    });
+    it('canSkip returns true only when planning artifacts have sequential Architect and Critic approval evidence', async () => {
+        const plansDir = join(tempDir, '.omx', 'plans');
+        await mkdir(plansDir, { recursive: true });
+        await writeFile(join(plansDir, 'prd-my-feature.md'), '# Plan\n');
+        await writeFile(join(plansDir, 'test-spec-my-feature.md'), '# Test Spec\n');
+        const stage = createRalplanStage();
+        assert.equal(stage.canSkip(makeCtx({
+            artifacts: {
+                ralplan: {
+                    ralplanConsensusGate: {
+                        complete: true,
+                        ralplan_architect_review: { agent_role: 'architect', verdict: 'approve', summary: 'architect approved' },
+                        ralplan_critic_review: { agent_role: 'critic', verdict: 'approve', summary: 'critic approved after architect' },
+                    },
+                },
+            },
+        })), true);
+    });
+    it('canSkip honors explicit session-scoped consensus state before root state', async () => {
+        const plansDir = join(tempDir, '.omx', 'plans');
+        const stateDir = join(tempDir, '.omx', 'state');
+        const sessionDir = join(stateDir, 'sessions', 'sess-explicit');
+        await mkdir(plansDir, { recursive: true });
+        await mkdir(sessionDir, { recursive: true });
+        await writeFile(join(plansDir, 'prd-my-feature.md'), '# Plan\n');
+        await writeFile(join(plansDir, 'test-spec-my-feature.md'), '# Test Spec\n');
+        await writeFile(join(stateDir, 'autopilot-state.json'), JSON.stringify({
+            state: {
+                handoff_artifacts: {
+                    ralplan_architect_review: { agent_role: 'architect', verdict: 'reject', approved: true },
+                    ralplan_critic_review: { agent_role: 'critic', verdict: 'approve' },
+                },
+            },
+        }));
+        await writeFile(join(sessionDir, 'autopilot-state.json'), JSON.stringify({
+            state: {
+                handoff_artifacts: {
+                    ralplan_architect_review: { agent_role: 'architect', verdict: 'approve' },
+                    ralplan_critic_review: { agent_role: 'critic', verdict: 'approve' },
+                },
+            },
+        }));
+        const stage = createRalplanStage();
+        assert.equal(stage.canSkip(makeCtx({ sessionId: 'sess-explicit' })), true);
+    });
+    it('canSkip fails closed when explicit session state is missing despite root consensus', async () => {
+        const plansDir = join(tempDir, '.omx', 'plans');
+        const stateDir = join(tempDir, '.omx', 'state');
+        await mkdir(plansDir, { recursive: true });
+        await mkdir(stateDir, { recursive: true });
+        await writeFile(join(plansDir, 'prd-my-feature.md'), '# Plan\n');
+        await writeFile(join(plansDir, 'test-spec-my-feature.md'), '# Test Spec\n');
+        await writeFile(join(stateDir, 'autopilot-state.json'), JSON.stringify({
+            state: {
+                handoff_artifacts: {
+                    ralplan_architect_review: { agent_role: 'architect', verdict: 'approve' },
+                    ralplan_critic_review: { agent_role: 'critic', verdict: 'approve' },
+                },
+            },
+        }));
+        const stage = createRalplanStage();
+        assert.equal(stage.canSkip(makeCtx({ sessionId: 'sess-missing' })), false);
+    });
+    it('canSkip fails closed for malformed explicit session ids instead of falling back to root consensus', async () => {
+        const plansDir = join(tempDir, '.omx', 'plans');
+        const stateDir = join(tempDir, '.omx', 'state');
+        await mkdir(plansDir, { recursive: true });
+        await mkdir(stateDir, { recursive: true });
+        await writeFile(join(plansDir, 'prd-my-feature.md'), '# Plan\n');
+        await writeFile(join(plansDir, 'test-spec-my-feature.md'), '# Test Spec\n');
+        await writeFile(join(stateDir, 'ralplan-state.json'), JSON.stringify({
+            ralplanConsensusGate: {
+                complete: true,
+                sequence: ['architect-review', 'critic-review'],
+                ralplan_architect_review: { agent_role: 'architect', verdict: 'approve' },
+                ralplan_critic_review: { agent_role: 'critic', verdict: 'approve' },
+            },
+        }));
+        const stage = createRalplanStage();
+        for (const sessionId of ['../bad', 'a'.repeat(65), '']) {
+            assert.equal(stage.canSkip(makeCtx({ sessionId })), false);
+        }
+    });
+    it('canSkip rejects blocker aliases even with approval-shaped booleans', async () => {
+        const plansDir = join(tempDir, '.omx', 'plans');
+        await mkdir(plansDir, { recursive: true });
+        await writeFile(join(plansDir, 'prd-my-feature.md'), '# Plan\n');
+        await writeFile(join(plansDir, 'test-spec-my-feature.md'), '# Test Spec\n');
+        const stage = createRalplanStage();
+        for (const blocker of [
+            { blocking: true },
+            { request_changes: true },
+            { requestChanges: true },
+            { status: 'request changes' },
+            { recommendation: 'changes-requested' },
+        ]) {
+            assert.equal(stage.canSkip(makeCtx({
+                artifacts: {
+                    ralplan: {
+                        ralplanConsensusGate: {
+                            complete: true,
+                            ralplan_architect_review: { agent_role: 'architect', verdict: 'approve' },
+                            ralplan_critic_review: { agent_role: 'critic', approved: true, clean: true, ...blocker },
+                        },
+                    },
+                },
+            })), false);
+        }
+    });
+    it('canSkip returns false when Critic evidence is recorded before Architect evidence', async () => {
+        const plansDir = join(tempDir, '.omx', 'plans');
+        await mkdir(plansDir, { recursive: true });
+        await writeFile(join(plansDir, 'prd-my-feature.md'), '# Plan\n');
+        await writeFile(join(plansDir, 'test-spec-my-feature.md'), '# Test Spec\n');
+        const stage = createRalplanStage();
+        assert.equal(stage.canSkip(makeCtx({
+            artifacts: {
+                ralplan: {
+                    ralplanConsensusGate: {
+                        complete: true,
+                        sequence: ['critic-review', 'architect-review'],
+                        ralplan_architect_review: { agent_role: 'architect', verdict: 'approve' },
+                        ralplan_critic_review: { agent_role: 'critic', verdict: 'approve' },
+                    },
+                },
+            },
+        })), false);
+    });
+    it('canSkip returns false when Critic timestamp predates Architect timestamp', async () => {
+        const plansDir = join(tempDir, '.omx', 'plans');
+        await mkdir(plansDir, { recursive: true });
+        await writeFile(join(plansDir, 'prd-my-feature.md'), '# Plan\n');
+        await writeFile(join(plansDir, 'test-spec-my-feature.md'), '# Test Spec\n');
+        const stage = createRalplanStage();
+        assert.equal(stage.canSkip(makeCtx({
+            artifacts: {
+                ralplan: {
+                    ralplanConsensusGate: {
+                        complete: true,
+                        sequence: ['architect-review', 'critic-review'],
+                        ralplan_architect_review: {
+                            agent_role: 'architect',
+                            verdict: 'approve',
+                            completed_at: '2026-05-21T10:05:00.000Z',
+                        },
+                        ralplan_critic_review: {
+                            agent_role: 'critic',
+                            verdict: 'approve',
+                            completed_at: '2026-05-21T10:00:00.000Z',
+                        },
+                    },
+                },
+            },
+        })), false);
+    });
+    it('canSkip ignores ambient OMX_ROOT consensus state for local PRD/test-spec-only artifacts', async () => {
+        const ambientRoot = await mkdtemp(join(tmpdir(), 'omx-ralplan-ambient-'));
+        const previousOmxRoot = process.env.OMX_ROOT;
+        try {
+            const plansDir = join(tempDir, '.omx', 'plans');
+            await mkdir(plansDir, { recursive: true });
+            await writeFile(join(plansDir, 'prd-local.md'), '# Plan\n');
+            await writeFile(join(plansDir, 'test-spec-local.md'), '# Test Spec\n');
+            const ambientStateDir = join(ambientRoot, '.omx', 'state');
+            await mkdir(ambientStateDir, { recursive: true });
+            await writeFile(join(ambientStateDir, 'ralplan-state.json'), JSON.stringify({
+                current_phase: 'complete',
+                planning_complete: true,
+                ralplan_consensus_gate: {
+                    complete: true,
+                    ralplan_architect_review: { agent_role: 'architect', verdict: 'approve', iteration: 1 },
+                    ralplan_critic_review: { agent_role: 'critic', verdict: 'approve', iteration: 1 },
+                },
+            }));
+            process.env.OMX_ROOT = ambientRoot;
+            const stage = createRalplanStage();
+            assert.equal(stage.canSkip(makeCtx()), false);
+        }
+        finally {
+            if (previousOmxRoot === undefined)
+                delete process.env.OMX_ROOT;
+            else
+                process.env.OMX_ROOT = previousOmxRoot;
+            await rm(ambientRoot, { recursive: true, force: true });
+        }
+    });
+    it('canSkip returns false for rejected consensus objects with approval-shaped booleans', async () => {
         const plansDir = join(tempDir, '.omx', 'plans');
         await mkdir(plansDir, { recursive: true });
         await writeFile(join(plansDir, 'prd-my-feature.md'), '# Plan\n');
         await writeFile(join(plansDir, 'test-spec-my-feature.md'), '# Test Spec\n');
         const stage = createRalplanStage();
-        assert.equal(stage.canSkip(makeCtx()), true);
+        assert.equal(stage.canSkip(makeCtx({
+            artifacts: {
+                ralplan: {
+                    ralplanConsensusGate: {
+                        complete: true,
+                        ralplan_architect_review: {
+                            agent_role: 'architect',
+                            verdict: 'reject',
+                            approved: true,
+                            clean: true,
+                        },
+                        ralplan_critic_review: {
+                            agent_role: 'critic',
+                            verdict: 'approve',
+                            approved: true,
+                            clean: true,
+                        },
+                    },
+                },
+            },
+        })), false);
+    });
+    it('canSkip returns false when consensus-shaped reviews do not record agent roles', async () => {
+        const plansDir = join(tempDir, '.omx', 'plans');
+        await mkdir(plansDir, { recursive: true });
+        await writeFile(join(plansDir, 'prd-my-feature.md'), '# Plan\n');
+        await writeFile(join(plansDir, 'test-spec-my-feature.md'), '# Test Spec\n');
+        const stage = createRalplanStage();
+        assert.equal(stage.canSkip(makeCtx({
+            artifacts: {
+                ralplan: {
+                    ralplanConsensusGate: {
+                        complete: true,
+                        ralplan_architect_review: { verdict: 'approve', summary: 'role missing' },
+                        ralplan_critic_review: { verdict: 'approve', summary: 'role missing' },
+                    },
+                },
+            },
+        })), false);
+    });
+    it('canSkip returns false when review history entries do not record agent roles', async () => {
+        const plansDir = join(tempDir, '.omx', 'plans');
+        await mkdir(plansDir, { recursive: true });
+        await writeFile(join(plansDir, 'prd-my-feature.md'), '# Plan\n');
+        await writeFile(join(plansDir, 'test-spec-my-feature.md'), '# Test Spec\n');
+        const stage = createRalplanStage();
+        assert.equal(stage.canSkip(makeCtx({
+            artifacts: {
+                ralplan: {
+                    review_history: [{
+                            architect_review: { verdict: 'approve', summary: 'role missing' },
+                            critic_review: { verdict: 'approve', summary: 'role missing' },
+                        }],
+                },
+            },
+        })), false);
+    });
+    it('canSkip returns false when review arrays do not record agent roles', async () => {
+        const plansDir = join(tempDir, '.omx', 'plans');
+        await mkdir(plansDir, { recursive: true });
+        await writeFile(join(plansDir, 'prd-my-feature.md'), '# Plan\n');
+        await writeFile(join(plansDir, 'test-spec-my-feature.md'), '# Test Spec\n');
+        const stage = createRalplanStage();
+        assert.equal(stage.canSkip(makeCtx({
+            artifacts: {
+                ralplan: {
+                    architectReviews: [{ verdict: 'approve', summary: 'role missing' }],
+                    criticReviews: [{ verdict: 'approve', summary: 'role missing' }],
+                },
+            },
+        })), false);
+    });
+    it('canSkip returns false when local state only has latest verdict fields', async () => {
+        const plansDir = join(tempDir, '.omx', 'plans');
+        const stateDir = join(tempDir, '.omx', 'state');
+        await mkdir(plansDir, { recursive: true });
+        await mkdir(stateDir, { recursive: true });
+        await writeFile(join(plansDir, 'prd-my-feature.md'), '# Plan\n');
+        await writeFile(join(plansDir, 'test-spec-my-feature.md'), '# Test Spec\n');
+        await writeFile(join(stateDir, 'ralplan-state.json'), JSON.stringify({
+            current_phase: 'complete',
+            planning_complete: true,
+            latest_architect_verdict: 'approve',
+            latest_critic_verdict: 'approve',
+        }));
+        const stage = createRalplanStage();
+        assert.equal(stage.canSkip(makeCtx()), false);
+    });
+    it('canSkip returns false when Architect and Critic roles are swapped', async () => {
+        const plansDir = join(tempDir, '.omx', 'plans');
+        await mkdir(plansDir, { recursive: true });
+        await writeFile(join(plansDir, 'prd-my-feature.md'), '# Plan\n');
+        await writeFile(join(plansDir, 'test-spec-my-feature.md'), '# Test Spec\n');
+        const stage = createRalplanStage();
+        assert.equal(stage.canSkip(makeCtx({
+            artifacts: {
+                ralplan: {
+                    ralplanConsensusGate: {
+                        complete: true,
+                        ralplan_architect_review: { agent_role: 'critic', verdict: 'approve' },
+                        ralplan_critic_review: { agent_role: 'architect', verdict: 'approve' },
+                    },
+                },
+            },
+        })), false);
     });
     it('canSkip returns false after non-clean code-review loopback even when plans exist', async () => {
         const plansDir = join(tempDir, '.omx', 'plans');
@@ -186,11 +506,100 @@ describe('RALPLAN Stage', () => {
         const result = await stage.run(makeCtx({ task: 'live ralplan run' }));
         const artifacts = result.artifacts;
         assert.equal(result.status, 'completed');
+        assert.equal(result.error, undefined);
         assert.equal(artifacts.runtime, true);
         assert.equal(artifacts.planningComplete, true);
+        assert.deepEqual(artifacts.ralplanConsensusGate, {
+            complete: true,
+            sequence: ['architect-review', 'critic-review'],
+            ralplan_architect_review: { agent_role: 'architect', iteration: 1, verdict: 'approve', summary: 'architect ok' },
+            ralplan_critic_review: { agent_role: 'critic', iteration: 1, verdict: 'approve', summary: 'critic ok' },
+            source: 'runtime-result',
+            blockedReason: null,
+        });
         assert.equal(artifacts.iteration, 1);
         assert.equal(artifacts.runtimeDrafted, true);
     });
+    it('fails runtime handoff when consensus approves but test spec does not match selected PRD', async () => {
+        const stage = createRalplanStage({
+            executor: {
+                async draft() {
+                    const plansDir = join(tempDir, '.omx', 'plans');
+                    await mkdir(plansDir, { recursive: true });
+                    const prdPath = join(plansDir, 'prd-new.md');
+                    await writeFile(prdPath, '# New runtime plan\n');
+                    await writeFile(join(plansDir, 'test-spec-old.md'), '# Stale runtime tests\n');
+                    return { summary: 'drafted mismatched artifacts', planPath: prdPath };
+                },
+                async architectReview() {
+                    return { verdict: 'approve', summary: 'architect ok' };
+                },
+                async criticReview() {
+                    return { verdict: 'approve', summary: 'critic ok' };
+                },
+            },
+        });
+        const result = await stage.run(makeCtx({ task: 'live ralplan mismatched artifacts' }));
+        const artifacts = result.artifacts;
+        assert.equal(result.status, 'failed');
+        assert.equal(result.error, 'ralplan_planning_artifacts_missing_after_consensus');
+        assert.equal(artifacts.planningComplete, false);
+        assert.equal(artifacts.ralplanConsensusGate.complete, true);
+    });
+    it('fails runtime handoff when consensus approves but required planning artifacts are missing', async () => {
+        const stage = createRalplanStage({
+            executor: {
+                async draft() {
+                    return { summary: 'draft without files' };
+                },
+                async architectReview() {
+                    return { verdict: 'approve', summary: 'architect ok' };
+                },
+                async criticReview() {
+                    return { verdict: 'approve', summary: 'critic ok' };
+                },
+            },
+        });
+        const result = await stage.run(makeCtx({ task: 'live ralplan no artifacts' }));
+        const artifacts = result.artifacts;
+        assert.equal(result.status, 'failed');
+        assert.equal(result.error, 'ralplan_planning_artifacts_missing_after_consensus');
+        assert.equal(artifacts.planningComplete, false);
+        assert.equal(artifacts.ralplanConsensusGate.complete, true);
+    });
+    it('fails runtime handoff when Critic has not approved after Architect', async () => {
+        const stage = createRalplanStage({
+            executor: {
+                async draft() {
+                    const plansDir = join(tempDir, '.omx', 'plans');
+                    await mkdir(plansDir, { recursive: true });
+                    const prdPath = join(plansDir, 'prd-runtime.md');
+                    await writeFile(prdPath, '# Runtime Plan\n');
+                    await writeFile(join(plansDir, 'test-spec-runtime.md'), '# Runtime Tests\n');
+                    return { summary: 'drafted', planPath: prdPath };
+                },
+                async architectReview() {
+                    return { verdict: 'approve', summary: 'architect ok' };
+                },
+                async criticReview() {
+                    return { verdict: 'iterate', summary: 'critic needs changes' };
+                },
+            },
+            maxIterations: 1,
+        });
+        const result = await stage.run(makeCtx({ task: 'live ralplan run' }));
+        const artifacts = result.artifacts;
+        assert.equal(result.status, 'failed');
+        assert.equal(result.error, 'ralplan_consensus_not_reached_after_1_iterations');
+        assert.deepEqual(artifacts.ralplanConsensusGate, {
+            complete: false,
+            sequence: ['architect-review', 'critic-review'],
+            ralplan_architect_review: null,
+            ralplan_critic_review: null,
+            source: null,
+            blockedReason: 'missing_sequential_architect_then_critic_approval',
+        });
+    });
     it('canSkip returns false for non-prd plan files', async () => {
         const plansDir = join(tempDir, '.omx', 'plans');
         await mkdir(plansDir, { recursive: true });
@@ -1000,13 +1409,13 @@ describe('Ralph Verify Stage', () => {
 // ---------------------------------------------------------------------------
 // Strict Autopilot stage tests
 // ---------------------------------------------------------------------------
-describe('Strict Autopilot Ralph Stage', () => {
+describe('Explicit Legacy Ralph Stage', () => {
     beforeEach(async () => { await setup(); });
     afterEach(async () => { await cleanup(); });
-    it('uses the strict phase name ralph', () => {
+    it('uses the explicit legacy phase name ralph', () => {
         assert.equal(createRalphStage().name, 'ralph');
     });
-    it('uses ralplan artifacts as the primary strict ralph execution input', async () => {
+    it('uses ralplan artifacts as the primary explicit legacy Ralph execution input', async () => {
         const result = await createRalphStage().run(makeCtx({
             artifacts: {
                 ralplan: { plan: 'approved plan' },
@@ -1017,14 +1426,56 @@ describe('Strict Autopilot Ralph Stage', () => {
         assert.deepEqual(descriptor.executionArtifacts, { plan: 'approved plan' });
     });
 });
+describe('Default Autopilot Ultragoal Stage Adapters', () => {
+    beforeEach(async () => { await setup(); });
+    afterEach(async () => { await cleanup(); });
+    it('creates a deep-interview descriptor and instruction', async () => {
+        const stage = createDeepInterviewStage();
+        assert.equal(stage.name, 'deep-interview');
+        const result = await stage.run(makeCtx());
+        const artifacts = result.artifacts;
+        assert.equal(artifacts.stage, 'deep-interview');
+        assert.match(artifacts.instruction, /^\$deep-interview /);
+        assert.match(buildDeepInterviewInstruction('clarify me'), /^\$deep-interview /);
+    });
+    it('creates an ultragoal descriptor with explicit team condition', async () => {
+        const stage = createUltragoalStage();
+        assert.equal(stage.name, 'ultragoal');
+        const result = await stage.run(makeCtx({ artifacts: { ralplan: { plan: 'approved' } } }));
+        const artifacts = result.artifacts;
+        const descriptor = artifacts.ultragoalDescriptor;
+        assert.equal(artifacts.stage, 'ultragoal');
+        assert.deepEqual(descriptor.ralplanArtifacts, { plan: 'approved' });
+        assert.match(artifacts.team_condition, /Launch \$team only inside an active Ultragoal story/);
+        assert.match(buildUltragoalInstruction('execute me'), /^\$ultragoal /);
+    });
+    it('creates an ultraqa gate that fails closed without evidence and can record clean skips', async () => {
+        const missingEvidence = await createUltraqaStage().run(makeCtx({
+            artifacts: { ultragoal: { tests: 'passed' }, 'code-review': { review_verdict: { clean: true } } },
+        }));
+        const missingArtifacts = missingEvidence.artifacts;
+        const missingVerdict = missingArtifacts.qa_verdict;
+        assert.equal(missingVerdict.clean, false);
+        assert.equal(missingArtifacts.return_to_ralplan_reason, 'UltraQA evidence missing; fail closed and return to ralplan.');
+        const skipped = await createUltraqaStage({ skipped: true, summary: 'Docs-only change; QA not applicable.' }).run(makeCtx());
+        const skippedArtifacts = skipped.artifacts;
+        const skippedVerdict = skippedArtifacts.qa_verdict;
+        assert.equal(skippedVerdict.clean, true);
+        assert.equal(skippedVerdict.skipped, true);
+        assert.equal(skippedArtifacts.return_to_ralplan_reason, null);
+        assert.match(buildUltraqaInstruction('qa me'), /^\$ultraqa /);
+    });
+});
 describe('Code Review Stage', () => {
     beforeEach(async () => { await setup(); });
     afterEach(async () => { await cleanup(); });
-    it('creates a strict code-review stage that fails closed without review evidence', async () => {
+    it('creates a code-review stage that fails closed without review evidence', async () => {
         const stage = createCodeReviewStage();
         assert.equal(stage.name, 'code-review');
-        const result = await stage.run(makeCtx({ artifacts: { ralph: { tests: 'passed' } } }));
+        const result = await stage.run(makeCtx({ artifacts: { ultragoal: { tests: 'passed' } } }));
         const artifacts = result.artifacts;
+        const descriptor = artifacts.codeReviewDescriptor;
+        assert.deepEqual(descriptor.executionArtifacts, { tests: 'passed' });
         const verdict = artifacts.review_verdict;
         assert.equal(result.status, 'completed');
         assert.equal(verdict.clean, false);