sofia-cli 0.1.1

package/dist/tests/unit/develop/ralphLoop.spec.js

@@ -0,0 +1,1248 @@
+/**
+ * T022: Unit tests for RalphLoop orchestrator.
+ *
+ * Verifies:
+ * - Lifecycle (validate → scaffold → install → iterate)
+ * - Termination on tests-passing
+ * - Termination on max-iterations
+ * - Iteration count tracking
+ * - Session persistence callback called after each iteration
+ * - Ctrl+C handling sets user-stopped
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { RalphLoop } from '../../../src/develop/ralphLoop.js';
+import { PocScaffolder, validatePocOutput } from '../../../src/develop/pocScaffolder.js';
+// ── Mocks ─────────────────────────────────────────────────────────────────────
+// Mock npm install to always succeed
+vi.mock('node:child_process', async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        spawn: vi.fn((cmd, args) => {
+            if (cmd === 'npm' && args.includes('install')) {
+                // Simulate successful npm install
+                const emitter = {
+                    stdout: { on: vi.fn() },
+                    stderr: { on: vi.fn() },
+                    on: vi.fn((event, cb) => {
+                        if (event === 'close')
+                            cb(0);
+                    }),
+                    kill: vi.fn(),
+                    killed: false,
+                };
+                return emitter;
+            }
+            return actual.spawn(cmd, args);
+        }),
+    };
+});
+// Mock validatePocOutput — default: valid
+vi.mock('../../../src/develop/pocScaffolder.js', async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        validatePocOutput: vi.fn().mockResolvedValue({ valid: true, missingFiles: [], errors: [] }),
+    };
+});
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function makeSession(overrides) {
+    const now = new Date().toISOString();
+    return {
+        sessionId: 'ralph-test-session',
+        schemaVersion: '1.0.0',
+        createdAt: now,
+        updatedAt: now,
+        phase: 'Develop',
+        status: 'Active',
+        participants: [],
+        artifacts: { generatedFiles: [] },
+        ideas: [
+            {
+                id: 'idea-1',
+                title: 'Test AI App',
+                description: 'A test AI application.',
+                workflowStepIds: [],
+            },
+        ],
+        selection: {
+            ideaId: 'idea-1',
+            selectionRationale: 'Best idea',
+            confirmedByUser: true,
+        },
+        plan: {
+            milestones: [{ id: 'm1', title: 'Setup', items: [] }],
+            architectureNotes: 'Node.js + TypeScript',
+        },
+        ...overrides,
+    };
+}
+function makeIo() {
+    return {
+        write: vi.fn(),
+        writeActivity: vi.fn(),
+        writeToolSummary: vi.fn(),
+        readInput: vi.fn().mockResolvedValue(null),
+        showDecisionGate: vi.fn(),
+        isJsonMode: false,
+        isTTY: false,
+    };
+}
+function makePassingClient() {
+    return {
+        createSession: vi.fn().mockResolvedValue({
+            send: vi.fn().mockReturnValue({
+                async *[Symbol.asyncIterator]() {
+                    yield {
+                        type: 'TextDelta',
+                        text: '```typescript file=src/index.ts\nexport function main() { return "ok"; }\n```',
+                        timestamp: '',
+                    };
+                },
+            }),
+            getHistory: () => [],
+        }),
+    };
+}
+function makePassingTestRunner() {
+    return {
+        run: vi.fn().mockResolvedValue({
+            passed: 2,
+            failed: 0,
+            skipped: 0,
+            total: 2,
+            durationMs: 300,
+            failures: [],
+            rawOutput: 'All tests pass',
+        }),
+    };
+}
+function _makeFailingTestRunner(failCount = 1) {
+    let callCount = 0;
+    return {
+        run: vi.fn().mockImplementation(async () => {
+            callCount++;
+            if (callCount > failCount) {
+                return {
+                    passed: 2,
+                    failed: 0,
+                    skipped: 0,
+                    total: 2,
+                    durationMs: 300,
+                    failures: [],
+                    rawOutput: 'All pass',
+                };
+            }
+            return {
+                passed: 0,
+                failed: 1,
+                skipped: 0,
+                total: 1,
+                durationMs: 400,
+                failures: [{ testName: 'suite > test A', message: 'Expected 1 but got 0' }],
+                rawOutput: 'FAIL tests/index.test.ts',
+            };
+        }),
+    };
+}
+function makeAlwaysFailingTestRunner() {
+    return {
+        run: vi.fn().mockResolvedValue({
+            passed: 0,
+            failed: 1,
+            skipped: 0,
+            total: 1,
+            durationMs: 400,
+            failures: [{ testName: 'suite > always fail', message: 'always fails' }],
+            rawOutput: 'FAIL',
+        }),
+    };
+}
+function makeFakeScaffolder(outputDir) {
+    return {
+        scaffold: vi.fn().mockImplementation(async () => {
+            // Create minimal required files
+            const { writeFile, mkdir } = await import('node:fs/promises');
+            await mkdir(join(outputDir, 'src'), { recursive: true });
+            await mkdir(join(outputDir, 'tests'), { recursive: true });
+            await writeFile(join(outputDir, 'package.json'), JSON.stringify({
+                name: 'test-poc',
+                scripts: { test: 'vitest run' },
+                dependencies: {},
+                devDependencies: {},
+            }), 'utf-8');
+            await writeFile(join(outputDir, 'src', 'index.ts'), 'export function main() {}', 'utf-8');
+            return {
+                createdFiles: ['package.json', 'src/index.ts'],
+                skippedFiles: [],
+                context: {
+                    projectName: 'test-poc',
+                    ideaTitle: 'Test',
+                    ideaDescription: 'Test',
+                    techStack: { language: 'TypeScript', runtime: 'Node.js 20', testRunner: 'npm test' },
+                    planSummary: 'Test',
+                    sessionId: 'ralph-test-session',
+                    outputDir,
+                },
+            };
+        }),
+        getTemplateFiles: () => ['package.json', 'src/index.ts'],
+    };
+}
+// ── Tests ─────────────────────────────────────────────────────────────────────
+describe('RalphLoop', () => {
+    let tmpDir;
+    beforeEach(async () => {
+        tmpDir = await mkdtemp(join(tmpdir(), 'sofia-ralph-test-'));
+    });
+    afterEach(async () => {
+        await rm(tmpDir, { recursive: true, force: true });
+        vi.clearAllMocks();
+    });
+    describe('validation', () => {
+        it('throws when session has no selection', async () => {
+            const session = makeSession({ selection: undefined });
+            const io = makeIo();
+            const client = makePassingClient();
+            const ralph = new RalphLoop({
+                client,
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 1,
+            });
+            await expect(ralph.run()).rejects.toThrow(/selection/i);
+        });
+        it('throws when session has no plan', async () => {
+            const session = makeSession({ plan: undefined });
+            const io = makeIo();
+            const client = makePassingClient();
+            const ralph = new RalphLoop({
+                client,
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 1,
+            });
+            await expect(ralph.run()).rejects.toThrow(/plan/i);
+        });
+    });
+    describe('lifecycle with passing tests', () => {
+        it('terminates with tests-passing when all tests pass immediately', async () => {
+            const session = makeSession();
+            const io = makeIo();
+            const client = makePassingClient();
+            const testRunner = makePassingTestRunner();
+            const scaffolder = makeFakeScaffolder(tmpDir);
+            const ralph = new RalphLoop({
+                client,
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 5,
+                testRunner,
+                scaffolder,
+            });
+            const result = await ralph.run();
+            expect(result.finalStatus).toBe('success');
+            expect(result.terminationReason).toBe('tests-passing');
+        });
+        it('tracks iteration count', async () => {
+            const session = makeSession();
+            const io = makeIo();
+            const client = makePassingClient();
+            const testRunner = makePassingTestRunner();
+            const scaffolder = makeFakeScaffolder(tmpDir);
+            const ralph = new RalphLoop({
+                client,
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 5,
+                testRunner,
+                scaffolder,
+            });
+            const result = await ralph.run();
+            // Iteration 1 (scaffold) + Iteration 2 (test run, passing)
+            expect(result.iterationsCompleted).toBeGreaterThanOrEqual(2);
+        });
+        it('calls onSessionUpdate after each iteration', async () => {
+            const session = makeSession();
+            const io = makeIo();
+            const client = makePassingClient();
+            const testRunner = makePassingTestRunner();
+            const scaffolder = makeFakeScaffolder(tmpDir);
+            const onSessionUpdate = vi.fn().mockResolvedValue(undefined);
+            const ralph = new RalphLoop({
+                client,
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 3,
+                testRunner,
+                scaffolder,
+                onSessionUpdate,
+            });
+            await ralph.run();
+            // Should be called at least once (after scaffold, after passing tests)
+            expect(onSessionUpdate).toHaveBeenCalled();
+        });
+        it('returns updated session with poc state', async () => {
+            const session = makeSession();
+            const io = makeIo();
+            const client = makePassingClient();
+            const testRunner = makePassingTestRunner();
+            const scaffolder = makeFakeScaffolder(tmpDir);
+            const ralph = new RalphLoop({
+                client,
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 5,
+                testRunner,
+                scaffolder,
+            });
+            const result = await ralph.run();
+            expect(result.session.poc).toBeDefined();
+            expect(result.session.poc.iterations.length).toBeGreaterThan(0);
+            expect(result.session.poc.iterations[0].outcome).toBe('scaffold');
+            expect(result.session.poc.finalStatus).toBe('success');
+        });
+    });
+    describe('termination on max-iterations', () => {
+        it('terminates with max-iterations when all tests keep failing', async () => {
+            const session = makeSession();
+            const io = makeIo();
+            const client = makePassingClient();
+            const testRunner = makeAlwaysFailingTestRunner();
+            const scaffolder = makeFakeScaffolder(tmpDir);
+            const ralph = new RalphLoop({
+                client,
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 3,
+                testRunner,
+                scaffolder,
+            });
+            const result = await ralph.run();
+            expect(result.terminationReason).toBe('max-iterations');
+            expect(result.iterationsCompleted).toBe(3); // 1 scaffold + 2 test iterations
+        });
+        it('sets finalStatus=partial when some tests pass at max-iterations', async () => {
+            const session = makeSession();
+            const io = makeIo();
+            const client = makePassingClient();
+            // Partially passing test runner
+            const testRunner = {
+                run: vi.fn().mockResolvedValue({
+                    passed: 1,
+                    failed: 1,
+                    skipped: 0,
+                    total: 2,
+                    durationMs: 400,
+                    failures: [{ testName: 'test B', message: 'fails' }],
+                    rawOutput: '',
+                }),
+            };
+            const scaffolder = makeFakeScaffolder(tmpDir);
+            const ralph = new RalphLoop({
+                client,
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 2,
+                testRunner,
+                scaffolder,
+            });
+            const result = await ralph.run();
+            expect(result.terminationReason).toBe('max-iterations');
+            expect(result.finalStatus).toBe('partial');
+        });
+        it('sets finalStatus=failed when no tests pass at max-iterations', async () => {
+            const session = makeSession();
+            const io = makeIo();
+            const client = makePassingClient();
+            const testRunner = makeAlwaysFailingTestRunner();
+            const scaffolder = makeFakeScaffolder(tmpDir);
+            const ralph = new RalphLoop({
+                client,
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 2,
+                testRunner,
+                scaffolder,
+            });
+            const result = await ralph.run();
+            expect(result.terminationReason).toBe('max-iterations');
+            expect(result.finalStatus).toBe('failed');
+        });
+        it('leaves session.poc.finalStatus unset when user stops (Ctrl+C)', async () => {
+            const session = makeSession();
+            const io = makeIo();
+            const testRunner = makeAlwaysFailingTestRunner();
+            const scaffolder = makeFakeScaffolder(tmpDir);
+            // Client that emits SIGINT mid-generation to simulate Ctrl+C
+            const client = {
+                createSession: vi.fn().mockResolvedValue({
+                    send: vi.fn().mockReturnValue({
+                        async *[Symbol.asyncIterator]() {
+                            process.emit('SIGINT');
+                            yield {
+                                type: 'TextDelta',
+                                text: '```typescript file=src/index.ts\nexport function main() { return "ok"; }\n```',
+                                timestamp: '',
+                            };
+                        },
+                    }),
+                    getHistory: () => [],
+                }),
+            };
+            const sessionUpdates = [];
+            const ralph = new RalphLoop({
+                client,
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 5,
+                testRunner,
+                scaffolder,
+                onSessionUpdate: async (s) => {
+                    sessionUpdates.push(s);
+                },
+            });
+            const result = await ralph.run();
+            expect(result.terminationReason).toBe('user-stopped');
+            // Contract: finalStatus must NOT be persisted to the session on user abort
+            expect(result.session.poc?.finalStatus).toBeUndefined();
+            // The persisted session updates should also not have finalStatus set
+            const lastUpdate = sessionUpdates[sessionUpdates.length - 1];
+            expect(lastUpdate?.poc?.finalStatus).toBeUndefined();
+        });
+    });
+    describe('event emission', () => {
+        it('emits events during loop lifecycle', async () => {
+            const session = makeSession();
+            const io = makeIo();
+            const client = makePassingClient();
+            const testRunner = makePassingTestRunner();
+            const scaffolder = makeFakeScaffolder(tmpDir);
+            const events = [];
+            const ralph = new RalphLoop({
+                client,
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 3,
+                testRunner,
+                scaffolder,
+                onEvent: (e) => events.push(e.type),
+            });
+            await ralph.run();
+            expect(events).toContain('Activity');
+        });
+    });
+    describe('output directory', () => {
+        it('returns outputDir in result', async () => {
+            const session = makeSession();
+            const io = makeIo();
+            const client = makePassingClient();
+            const testRunner = makePassingTestRunner();
+            const scaffolder = makeFakeScaffolder(tmpDir);
+            const ralph = new RalphLoop({
+                client,
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 3,
+                testRunner,
+                scaffolder,
+            });
+            const result = await ralph.run();
+            expect(result.outputDir).toBe(tmpDir);
+        });
+    });
+    describe('final test run after max iterations (F006)', () => {
+        it('runs a final test after the last LLM iteration and returns success when tests pass', async () => {
+            const session = makeSession();
+            const io = makeIo();
+            const client = makePassingClient();
+            const scaffolder = makeFakeScaffolder(tmpDir);
+            // First test run fails, second (final run after loop) passes
+            let runCount = 0;
+            const testRunner = {
+                run: vi.fn().mockImplementation(async () => {
+                    runCount++;
+                    if (runCount <= 1) {
+                        return {
+                            passed: 0,
+                            failed: 1,
+                            skipped: 0,
+                            total: 1,
+                            durationMs: 100,
+                            failures: [{ testName: 'test A', message: 'fails' }],
+                            rawOutput: 'FAIL',
+                        };
+                    }
+                    return {
+                        passed: 1,
+                        failed: 0,
+                        skipped: 0,
+                        total: 1,
+                        durationMs: 100,
+                        failures: [],
+                        rawOutput: 'PASS',
+                    };
+                }),
+            };
+            const ralph = new RalphLoop({
+                client,
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 2, // scaffold + 1 iterate = 2 iterations, then final test
+                testRunner,
+                scaffolder,
+            });
+            const result = await ralph.run();
+            // The final test run detected the fix, so status should be success
+            expect(result.finalStatus).toBe('success');
+            expect(result.terminationReason).toBe('tests-passing');
+        });
+    });
+    describe('SIGINT handler stale session (F009)', () => {
+        it('persists latest session with iteration data when SIGINT fires after iterations', async () => {
+            const session = makeSession();
+            const io = makeIo();
+            const client = makePassingClient();
+            const scaffolder = makeFakeScaffolder(tmpDir);
+            let persistedSession = null;
+            // Slow test runner: yields after first call so SIGINT can fire
+            let runCount = 0;
+            const testRunner = {
+                run: vi.fn().mockImplementation(async () => {
+                    runCount++;
+                    // After first iteration completes, delay so SIGINT can fire
+                    if (runCount >= 2) {
+                        await new Promise((resolve) => setTimeout(resolve, 500));
+                    }
+                    return {
+                        passed: 0,
+                        failed: 1,
+                        skipped: 0,
+                        total: 1,
+                        durationMs: 100,
+                        failures: [{ testName: 'test A', message: 'fails' }],
+                        rawOutput: 'FAIL',
+                    };
+                }),
+            };
+            const onSessionUpdate = vi.fn().mockImplementation(async (s) => {
+                persistedSession = s;
+            });
+            const ralph = new RalphLoop({
+                client,
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 10,
+                testRunner,
+                scaffolder,
+                onSessionUpdate,
+            });
+            // Start the loop, then fire SIGINT after enough time for first iteration
+            const runPromise = ralph.run();
+            // Wait for at least scaffold + first test run iteration
+            await new Promise((resolve) => setTimeout(resolve, 300));
+            process.emit('SIGINT', 'SIGINT');
+            const result = await runPromise;
+            expect(result.terminationReason).toBe('user-stopped');
+            // The persisted session should have iteration data from completed iterations
+            expect(persistedSession).not.toBeNull();
+            expect(persistedSession.poc).toBeDefined();
+            expect(persistedSession.poc.iterations.length).toBeGreaterThanOrEqual(1);
+        });
+    });
+    describe('user-stopped status (F011)', () => {
+        it('returns finalStatus=partial when user stops and some tests were passing', async () => {
+            const session = makeSession();
+            const io = makeIo();
+            const client = makePassingClient();
+            const scaffolder = makeFakeScaffolder(tmpDir);
+            // Partially passing test runner that delays so SIGINT can fire
+            let runCount = 0;
+            const testRunner = {
+                run: vi.fn().mockImplementation(async () => {
+                    runCount++;
+                    if (runCount >= 2) {
+                        await new Promise((resolve) => setTimeout(resolve, 500));
+                    }
+                    return {
+                        passed: 1,
+                        failed: 1,
+                        skipped: 0,
+                        total: 2,
+                        durationMs: 100,
+                        failures: [{ testName: 'test B', message: 'fails' }],
+                        rawOutput: 'PARTIAL',
+                    };
+                }),
+            };
+            const ralph = new RalphLoop({
+                client,
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 10,
+                testRunner,
+                scaffolder,
+            });
+            const runPromise = ralph.run();
+            await new Promise((resolve) => setTimeout(resolve, 300));
+            process.emit('SIGINT', 'SIGINT');
+            const result = await runPromise;
+            expect(result.terminationReason).toBe('user-stopped');
+            expect(result.finalStatus).toBe('partial');
+        });
+    });
+    // SKIPPED: Auto-push to GitHub removed per user safety requirements
+    // sofIA now initializes git locally only — users push manually
+    describe.skip('GitHub MCP adapter integration', () => {
+        it('reads written files from disk and passes their content to pushFiles', async () => {
+            const session = makeSession();
+            const io = makeIo();
+            // LLM returns a file with known content
+            const knownContent = 'export function main() { return "hello"; }\n';
+            const client = {
+                createSession: vi.fn().mockResolvedValue({
+                    send: vi.fn().mockReturnValue({
+                        async *[Symbol.asyncIterator]() {
+                            yield {
+                                type: 'TextDelta',
+                                text: `\`\`\`typescript file=src/index.ts\n${knownContent}\`\`\``,
+                                timestamp: '',
+                            };
+                        },
+                    }),
+                    getHistory: () => [],
+                }),
+            };
+            // Fail on first run so the LLM turn (and pushFiles) is reached; pass on second
+            let runCount = 0;
+            const testRunner = {
+                run: vi.fn().mockImplementation(async () => {
+                    runCount++;
+                    if (runCount === 1) {
+                        return {
+                            passed: 0,
+                            failed: 1,
+                            skipped: 0,
+                            total: 1,
+                            durationMs: 100,
+                            failures: [{ testName: 'main > works', message: 'not implemented' }],
+                            rawOutput: 'FAIL',
+                        };
+                    }
+                    return {
+                        passed: 1,
+                        failed: 0,
+                        skipped: 0,
+                        total: 1,
+                        durationMs: 100,
+                        failures: [],
+                        rawOutput: 'OK',
+                    };
+                }),
+            };
+            const scaffolder = makeFakeScaffolder(tmpDir);
+            // Create a mock GitHub adapter that captures pushFiles calls
+            const pushFilesMock = vi.fn().mockResolvedValue({ available: true, commitSha: 'abc123' });
+            const _githubAdapter = {
+                isAvailable: () => true,
+                getRepoUrl: () => 'https://github.com/acme/poc-test',
+                pushFiles: pushFilesMock,
+                createRepository: vi.fn().mockResolvedValue({
+                    available: true,
+                    repoUrl: 'https://github.com/acme/poc-test',
+                    repoName: 'poc-test',
+                }),
+            };
+            const ralph = new RalphLoop({
+                client,
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 5,
+                testRunner,
+                scaffolder,
+            });
+            await ralph.run();
+            // pushFiles should have been called at least twice:
+            // call[0] = scaffold push, call[1+] = iteration pushes
+            expect(pushFilesMock.mock.calls.length).toBeGreaterThanOrEqual(2);
+            // The iteration push (call[1]) should contain the LLM-written file content
+            const callArgs = pushFilesMock.mock.calls[1][0];
+            const pushedFile = callArgs.files.find((f) => f.path === 'src/index.ts');
+            expect(pushedFile).toBeDefined();
+            expect(pushedFile.content).toBe(knownContent);
+            expect(pushedFile.content).not.toBe('');
+        });
+    });
+    describe('validatePocOutput integration (F027)', () => {
+        it('downgrades success to partial when validatePocOutput reports missing files', async () => {
+            // Mock validatePocOutput to fail
+            vi.mocked(validatePocOutput).mockResolvedValueOnce({
+                valid: false,
+                missingFiles: ['README.md'],
+                errors: [],
+            });
+            const session = makeSession();
+            const io = makeIo();
+            const testRunner = {
+                run: vi.fn().mockResolvedValue({
+                    passed: 3,
+                    failed: 0,
+                    skipped: 0,
+                    total: 3,
+                    durationMs: 100,
+                    failures: [],
+                    rawOutput: 'ALL PASS',
+                }),
+            };
+            const ralph = new RalphLoop({
+                client: makePassingClient(),
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 5,
+                testRunner,
+                scaffolder: makeFakeScaffolder(tmpDir),
+            });
+            const result = await ralph.run();
+            expect(result.finalStatus).toBe('partial');
+            expect(result.terminationReason).toBe('tests-passing');
+            // validatePocOutput should have been called
+            expect(validatePocOutput).toHaveBeenCalledWith(tmpDir);
+        });
+        it('keeps success when validatePocOutput reports valid', async () => {
+            vi.mocked(validatePocOutput).mockResolvedValueOnce({
+                valid: true,
+                missingFiles: [],
+                errors: [],
+            });
+            const session = makeSession();
+            const io = makeIo();
+            const testRunner = {
+                run: vi.fn().mockResolvedValue({
+                    passed: 3,
+                    failed: 0,
+                    skipped: 0,
+                    total: 3,
+                    durationMs: 100,
+                    failures: [],
+                    rawOutput: 'ALL PASS',
+                }),
+            };
+            const ralph = new RalphLoop({
+                client: makePassingClient(),
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 5,
+                testRunner,
+                scaffolder: makeFakeScaffolder(tmpDir),
+            });
+            const result = await ralph.run();
+            expect(result.finalStatus).toBe('success');
+            expect(validatePocOutput).toHaveBeenCalledWith(tmpDir);
+        });
+    });
+    // ── Resume iteration seeding (T013) ─────────────────────────────────────
+    describe('resume iteration seeding', () => {
+        it('seeds iterations from session.poc.iterations and starts from correct iterNum', async () => {
+            const io = makeIo();
+            const testRunner = makePassingTestRunner();
+            const session = makeSession({
+                poc: {
+                    repoSource: 'local',
+                    iterations: [
+                        {
+                            iteration: 1,
+                            startedAt: new Date().toISOString(),
+                            endedAt: new Date().toISOString(),
+                            outcome: 'scaffold',
+                            filesChanged: ['package.json'],
+                        },
+                        {
+                            iteration: 2,
+                            startedAt: new Date().toISOString(),
+                            endedAt: new Date().toISOString(),
+                            outcome: 'tests-failing',
+                            filesChanged: ['src/index.ts'],
+                            testResults: {
+                                passed: 1,
+                                failed: 1,
+                                skipped: 0,
+                                total: 2,
+                                durationMs: 100,
+                                failures: [{ testName: 'test1', message: 'fail' }],
+                            },
+                        },
+                    ],
+                },
+            });
+            const ralph = new RalphLoop({
+                client: makePassingClient(),
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 10,
+                testRunner,
+                scaffolder: makeFakeScaffolder(tmpDir),
+                checkpoint: {
+                    hasPriorRun: true,
+                    completedIterations: 2,
+                    lastIterationIncomplete: false,
+                    resumeFromIteration: 3,
+                    canSkipScaffold: false,
+                    priorFinalStatus: undefined,
+                    priorIterations: session.poc.iterations,
+                },
+            });
+            const result = await ralph.run();
+            // Iterations should include the 2 prior ones + scaffold (no skip) + tests-passing
+            expect(result.iterationsCompleted).toBeGreaterThanOrEqual(3);
+            expect(result.finalStatus).toBe('success');
+        });
+        it('skips scaffold when checkpoint says canSkipScaffold=true (T014)', async () => {
+            const io = makeIo();
+            const testRunner = makePassingTestRunner();
+            const scaffolder = makeFakeScaffolder(tmpDir);
+            const session = makeSession({
+                poc: {
+                    repoSource: 'local',
+                    iterations: [
+                        {
+                            iteration: 1,
+                            startedAt: new Date().toISOString(),
+                            endedAt: new Date().toISOString(),
+                            outcome: 'scaffold',
+                            filesChanged: [],
+                        },
+                    ],
+                },
+            });
+            const ralph = new RalphLoop({
+                client: makePassingClient(),
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 10,
+                testRunner,
+                scaffolder,
+                checkpoint: {
+                    hasPriorRun: true,
+                    completedIterations: 1,
+                    lastIterationIncomplete: false,
+                    resumeFromIteration: 2,
+                    canSkipScaffold: true,
+                    priorFinalStatus: undefined,
+                    priorIterations: session.poc.iterations,
+                },
+            });
+            await ralph.run();
+            // Scaffold should NOT have been called — it was skipped
+            expect(scaffolder.scaffold).not.toHaveBeenCalled();
+            // Should log that scaffold was skipped
+            expect(io.writeActivity).toHaveBeenCalledWith(expect.stringContaining('Skipping scaffold'));
+        });
+        it('pops incomplete last iteration and re-runs it (T015, FR-001a)', async () => {
+            const io = makeIo();
+            const testRunner = makePassingTestRunner();
+            const incompleteIter = {
+                iteration: 2,
+                startedAt: new Date().toISOString(),
+                outcome: 'tests-failing',
+                filesChanged: [],
+                // No testResults — incomplete
+            };
+            const session = makeSession({
+                poc: {
+                    repoSource: 'local',
+                    iterations: [
+                        {
+                            iteration: 1,
+                            startedAt: new Date().toISOString(),
+                            endedAt: new Date().toISOString(),
+                            outcome: 'scaffold',
+                            filesChanged: [],
+                        },
+                        incompleteIter,
+                    ],
+                },
+            });
+            const ralph = new RalphLoop({
+                client: makePassingClient(),
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 10,
+                testRunner,
+                scaffolder: makeFakeScaffolder(tmpDir),
+                checkpoint: {
+                    hasPriorRun: true,
+                    completedIterations: 1,
+                    lastIterationIncomplete: true,
+                    resumeFromIteration: 2,
+                    canSkipScaffold: false,
+                    priorFinalStatus: undefined,
+                    priorIterations: [session.poc.iterations[0]], // Only completed iters
+                },
+            });
+            const result = await ralph.run();
+            // Should log about re-running incomplete iteration
+            expect(io.writeActivity).toHaveBeenCalledWith(expect.stringContaining('Re-running incomplete iteration'));
+            expect(result.finalStatus).toBe('success');
+        });
+        it('re-scaffolds when output directory is missing but iterations exist (T018, FR-007)', async () => {
+            const io = makeIo();
+            const testRunner = makePassingTestRunner();
+            const scaffolder = makeFakeScaffolder(tmpDir);
+            const session = makeSession({
+                poc: {
+                    repoSource: 'local',
+                    iterations: [
+                        {
+                            iteration: 1,
+                            startedAt: new Date().toISOString(),
+                            endedAt: new Date().toISOString(),
+                            outcome: 'scaffold',
+                            filesChanged: [],
+                        },
+                    ],
+                },
+            });
+            const ralph = new RalphLoop({
+                client: makePassingClient(),
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 10,
+                testRunner,
+                scaffolder,
+                checkpoint: {
+                    hasPriorRun: true,
+                    completedIterations: 1,
+                    lastIterationIncomplete: false,
+                    resumeFromIteration: 2,
+                    canSkipScaffold: false, // Output dir missing
+                    priorFinalStatus: undefined,
+                    priorIterations: session.poc.iterations,
+                },
+            });
+            await ralph.run();
+            // Scaffold SHOULD have been called since canSkipScaffold is false
+            expect(scaffolder.scaffold).toHaveBeenCalled();
+            expect(io.writeActivity).toHaveBeenCalledWith(expect.stringContaining('re-scaffolding'));
+        });
+    });
+    // SKIPPED: Auto-push to GitHub removed per user safety requirements
+    // sofIA now initializes git locally only — users push manually
+    describe.skip('post-scaffold push (T024 — US2)', () => {
+        it('pushes scaffold files to GitHub after npm install, before first test iteration', async () => {
+            const session = makeSession();
+            const io = makeIo();
+            const client = makePassingClient();
+            const testRunner = makePassingTestRunner();
+            const scaffolder = makeFakeScaffolder(tmpDir);
+            const pushOrder = [];
+            const pushFilesMock = vi.fn().mockImplementation(async () => {
+                pushOrder.push('pushFiles');
+                return { available: true, commitSha: 'scaffold-sha' };
+            });
+            const _githubAdapter = {
+                isAvailable: () => true,
+                getRepoUrl: () => 'https://github.com/acme/poc-test',
+                pushFiles: pushFilesMock,
+                createRepository: vi.fn().mockResolvedValue({
+                    available: true,
+                    repoUrl: 'https://github.com/acme/poc-test',
+                    repoName: 'poc-test',
+                }),
+            };
+            // Wrap testRunner.run to record ordering
+            const originalRun = testRunner.run;
+            testRunner.run = vi
+                .fn()
+                .mockImplementation(async (...args) => {
+                pushOrder.push('testRun');
+                return originalRun(...args);
+            });
+            const ralph = new RalphLoop({
+                client,
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 3,
+                testRunner,
+                scaffolder,
+            });
+            await ralph.run();
+            // pushFiles should have been called at least once for the scaffold
+            expect(pushFilesMock).toHaveBeenCalled();
+            const firstPushArgs = pushFilesMock.mock.calls[0][0];
+            // Should push the scaffold files ('package.json', 'src/index.ts')
+            expect(firstPushArgs.files.length).toBeGreaterThanOrEqual(1);
+            const packageJson = firstPushArgs.files.find((f) => f.path === 'package.json');
+            expect(packageJson).toBeDefined();
+            expect(packageJson.content).not.toBe('');
+            const indexTs = firstPushArgs.files.find((f) => f.path === 'src/index.ts');
+            expect(indexTs).toBeDefined();
+            expect(indexTs.content).not.toBe('');
+            // Commit message should indicate scaffold
+            expect(firstPushArgs.commitMessage).toContain('scaffold');
+            // The scaffold push should come BEFORE the first test run
+            const firstPush = pushOrder.indexOf('pushFiles');
+            const firstTest = pushOrder.indexOf('testRun');
+            expect(firstPush).toBeLessThan(firstTest);
+        });
+        it('always re-runs dependency install even when scaffolding is skipped (T065, FR-003)', async () => {
+            const io = makeIo();
+            const testRunner = makePassingTestRunner();
+            const scaffolder = makeFakeScaffolder(tmpDir);
+            const session = makeSession({
+                poc: {
+                    repoSource: 'local',
+                    iterations: [
+                        {
+                            iteration: 1,
+                            startedAt: new Date().toISOString(),
+                            endedAt: new Date().toISOString(),
+                            outcome: 'scaffold',
+                            filesChanged: [],
+                        },
+                    ],
+                },
+            });
+            const ralph = new RalphLoop({
+                client: makePassingClient(),
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 10,
+                testRunner,
+                scaffolder,
+                checkpoint: {
+                    hasPriorRun: true,
+                    completedIterations: 1,
+                    lastIterationIncomplete: false,
+                    resumeFromIteration: 2,
+                    canSkipScaffold: true,
+                    priorFinalStatus: undefined,
+                    priorIterations: session.poc.iterations,
+                },
+            });
+            await ralph.run();
+            // Scaffold should be skipped
+            expect(scaffolder.scaffold).not.toHaveBeenCalled();
+            // But install should still run
+            expect(io.writeActivity).toHaveBeenCalledWith(expect.stringContaining('Re-running dependency installation'));
+        });
+        it('includes prior iteration history in LLM prompt context (T066, FR-004)', async () => {
+            const io = makeIo();
+            const testRunner = makeAlwaysFailingTestRunner();
+            const priorIters = [
+                {
+                    iteration: 1,
+                    startedAt: new Date().toISOString(),
+                    endedAt: new Date().toISOString(),
+                    outcome: 'scaffold',
+                    filesChanged: ['package.json'],
+                },
+                {
+                    iteration: 2,
+                    startedAt: new Date().toISOString(),
+                    endedAt: new Date().toISOString(),
+                    outcome: 'tests-failing',
+                    filesChanged: ['src/index.ts'],
+                    testResults: {
+                        passed: 1,
+                        failed: 1,
+                        skipped: 0,
+                        total: 2,
+                        durationMs: 100,
+                        failures: [{ testName: 'test1', message: 'fail' }],
+                    },
+                },
+            ];
+            const session = makeSession({
+                poc: {
+                    repoSource: 'local',
+                    iterations: priorIters,
+                },
+            });
+            // Track LLM prompts
+            const capturedPrompts = [];
+            const client = {
+                createSession: vi.fn().mockResolvedValue({
+                    send: vi.fn().mockImplementation((msg) => {
+                        capturedPrompts.push(msg.content);
+                        return {
+                            async *[Symbol.asyncIterator]() {
+                                yield {
+                                    type: 'TextDelta',
+                                    text: '```typescript file=src/index.ts\nexport const x = 1;\n```',
+                                    timestamp: '',
+                                };
+                            },
+                        };
+                    }),
+                    getHistory: () => [],
+                }),
+            };
+            const ralph = new RalphLoop({
+                client,
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 4,
+                testRunner,
+                scaffolder: makeFakeScaffolder(tmpDir),
+                checkpoint: {
+                    hasPriorRun: true,
+                    completedIterations: 2,
+                    lastIterationIncomplete: false,
+                    resumeFromIteration: 3,
+                    canSkipScaffold: false,
+                    priorFinalStatus: undefined,
+                    priorIterations: priorIters,
+                },
+            });
+            await ralph.run();
+            // The LLM should have received prior iteration history
+            // The context enrichment path merges priorHistoryContext into mcpContext
+            // This is hard to test directly without peeking at internals, but we can verify
+            // that the prior iterations were seeded properly
+            expect(io.writeActivity).toHaveBeenCalledWith(expect.stringContaining('Re-running dependency installation'));
+        });
+        it('resume decision logging emits info-level messages (T067, FR-007a)', async () => {
+            const io = makeIo();
+            const testRunner = makePassingTestRunner();
+            const scaffolder = makeFakeScaffolder(tmpDir);
+            const session = makeSession({
+                poc: {
+                    repoSource: 'local',
+                    iterations: [
+                        {
+                            iteration: 1,
+                            startedAt: new Date().toISOString(),
+                            endedAt: new Date().toISOString(),
+                            outcome: 'scaffold',
+                            filesChanged: [],
+                        },
+                    ],
+                },
+            });
+            const ralph = new RalphLoop({
+                client: makePassingClient(),
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 10,
+                testRunner,
+                scaffolder,
+                checkpoint: {
+                    hasPriorRun: true,
+                    completedIterations: 1,
+                    lastIterationIncomplete: false,
+                    resumeFromIteration: 2,
+                    canSkipScaffold: true,
+                    priorFinalStatus: undefined,
+                    priorIterations: session.poc.iterations,
+                },
+            });
+            await ralph.run();
+            // Should have logged skip scaffold, re-run install messages
+            const calls = io.writeActivity.mock.calls.flat();
+            expect(calls.some((c) => c.includes('Skipping scaffold'))).toBe(true);
+            expect(calls.some((c) => c.includes('Re-running dependency installation'))).toBe(true);
+        });
+    });
+    // ── T073: TODO marker rescan after iteration updates .sofia-metadata.json ──
+    describe('TODO marker rescan after iteration (T073)', () => {
+        it('calls scanAndRecordTodos after each failing iteration', async () => {
+            const scanSpy = vi
+                .spyOn(PocScaffolder, 'scanAndRecordTodos')
+                .mockResolvedValue({ totalInitial: 3, remaining: 2, markers: [] });
+            const session = makeSession();
+            const io = {
+                write: vi.fn(),
+                writeActivity: vi.fn(),
+                writeToolSummary: vi.fn(),
+                readInput: vi.fn().mockResolvedValue(null),
+                showDecisionGate: vi.fn(),
+                isJsonMode: false,
+                isTTY: false,
+            };
+            const testRunner = makeAlwaysFailingTestRunner();
+            const client = makePassingClient();
+            const scaffolder = makeFakeScaffolder(tmpDir);
+            const ralph = new RalphLoop({
+                client,
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 2,
+                testRunner,
+                scaffolder,
+            });
+            await ralph.run();
+            // scanAndRecordTodos should have been called for each failing iteration
+            expect(scanSpy).toHaveBeenCalled();
+            expect(scanSpy).toHaveBeenCalledWith(tmpDir);
+            scanSpy.mockRestore();
+        });
+    });
+    // ── T054: infiniteSessions config forwarding ──────────────────────────────
+    describe('infiniteSessions config (T054)', () => {
+        it('passes infiniteSessions config to createSession for context management', async () => {
+            const createSessionSpy = vi.fn().mockResolvedValue({
+                send: vi.fn().mockReturnValue({
+                    async *[Symbol.asyncIterator]() {
+                        yield {
+                            type: 'TextDelta',
+                            text: '```typescript file=src/index.ts\nexport function main() { return "ok"; }\n```',
+                            timestamp: '',
+                        };
+                    },
+                }),
+                getHistory: () => [],
+            });
+            const client = { createSession: createSessionSpy };
+            const io = makeIo();
+            const session = makeSession();
+            const testRunner = makeAlwaysFailingTestRunner();
+            const scaffolder = makeFakeScaffolder(tmpDir);
+            const ralph = new RalphLoop({
+                client,
+                io,
+                session,
+                outputDir: tmpDir,
+                maxIterations: 2,
+                testRunner,
+                scaffolder,
+            });
+            await ralph.run();
+            expect(createSessionSpy).toHaveBeenCalledWith(expect.objectContaining({
+                infiniteSessions: {
+                    backgroundCompactionThreshold: 0.7,
+                    bufferExhaustionThreshold: 0.9,
+                },
+            }));
+        });
+    });
+});