sneakoscope 2.0.13 → 2.0.14

package/dist/core/research/implementation-blueprint-densifier.js

@@ -0,0 +1,124 @@
+import path from 'node:path';
+import { nowIso, runProcess } from '../fsx.js';
+import {} from '../codex-control/codex-control-plane.js';
+import { defaultImplementationBlueprint } from './implementation-blueprint.js';
+export async function densifyImplementationBlueprint(input) {
+    const fileMap = await repositoryFileMap(input.root);
+    const likelyFiles = likelyTargetFiles(fileMap, input.plan, input.claimMatrix);
+    const possibleNewFiles = possibleNewResearchFiles(fileMap);
+    const base = input.existingBlueprint || defaultImplementationBlueprint(input.plan);
+    const claims = Array.isArray(input.claimMatrix?.claims) ? input.claimMatrix.claims : [];
+    const keyClaimIds = Array.isArray(input.claimMatrix?.key_claim_ids) ? input.claimMatrix.key_claim_ids : claims.slice(0, 8).map((claim) => claim.id);
+    const sections = [
+        section('problem', 'Problem', `Research currently must prove it executes stage-aware source shard runtime instead of relying on summary-style final.md output. The handoff should preserve ${keyClaimIds.length} key claim ids and all source-ledger evidence before code work begins.`, keyClaimIds, likelyFiles.slice(0, 8), ['Confirm the follow-up route reads claim-evidence-matrix.json and source-ledger.json before implementation.']),
+        section('decision', 'Decision', 'Use a dependency-aware research cycle with source_shard, source_merge, claim_matrix_build, falsification, implementation_blueprint, experiment_plan, synthesis, final_review, and verification stages. Keep Research read-only against repository source and write only mission artifacts.', keyClaimIds, likelyFiles.slice(0, 8), ['Default research run calls runResearchCycle; legacy final.md loop is opt-in only.']),
+        section('architecture', 'Architecture', 'The runtime is split into source shard generation, source-ledger merge, claim builder, blueprint densifier, final reviewer, blackbox scripts, and CLI status output. Each stage writes a ResearchStageResult under research/cycle-N/stages.', keyClaimIds, likelyFiles, ['Stage result artifacts list concrete output_artifacts for every passed stage.']),
+        section('interfaces', 'API And Schema Changes', `Existing files should expose typed contracts for shard outputs, stage results, merged source ledgers, Codex final review outputs, and concrete blueprint fields. Possible new files: ${possibleNewFiles.join(', ')}.`, keyClaimIds, likelyFiles, ['Schemas exist for research-source-shard and research-final-review.']),
+        section('data_contracts', 'Data Contracts', 'Source rows must preserve id, layer, kind, title, locator, publisher_or_author, accessed_at, reliability, credibility, stance, and claim_ids. Claim rows must preserve source_ids, counterevidence_ids, triangulation layers, confidence, and test_or_probe.', keyClaimIds, ['schemas/research/research-source-shard.schema.json', 'schemas/research/claim-evidence-matrix.schema.json'], ['Source quality report returns ok only when source metadata and citation coverage are complete.']),
+        section('execution_plan', 'Step By Step Implementation', implementationSteps(likelyFiles, possibleNewFiles).join('\n'), keyClaimIds, likelyFiles, ['Run research stage runtime blackbox, short-report rejection, complete-package fixture, and codex-sdk research pipeline gates.']),
+        section('verification_plan', 'Verification Plan', 'Run the release truth, research quality, source shard, source merge, claim builder, blueprint densifier, final reviewer, codex-sdk research pipeline, release DAG, and release check commands listed in the directive.', keyClaimIds, ['package.json', 'release-gates.v2.json', 'src/scripts/release-dag-full-coverage-check.ts'], ['All directive final checklist commands either pass or have a documented blocker.']),
+        section('risks_and_rollbacks', 'Risks And Rollbacks', 'The main risk is accepting deterministic fixture text as public-ready proof. Roll back by disabling new release gates only if the gate itself is wrong, not if implementation is incomplete. Research must block when live Codex/GPT final review is unavailable outside mock fixtures.', keyClaimIds, likelyFiles, ['A rollback keeps source mutation outside Research and restores package version metadata consistently.'])
+    ];
+    return {
+        ...base,
+        schema: 'sks.research-implementation-blueprint.v1',
+        generated_at: nowIso(),
+        prompt: input.plan?.prompt || base.prompt || '',
+        implementation_allowed_in_research: false,
+        handoff_route: '$Team',
+        repository_aware: true,
+        existing_files: likelyFiles,
+        possible_new_files: possibleNewFiles,
+        api_schema_changes: [
+            'ResearchStageResult contract for every executed stage.',
+            'ResearchSourceShardOutput contract for source layer partials.',
+            'Codex/GPT final reviewer merged with static review.'
+        ],
+        test_commands: [
+            'npm run research:stage-cycle-runtime-blackbox',
+            'npm run research:short-report-rejection',
+            'npm run research:complete-package-fixture',
+            'npm run codex-sdk:research-pipeline',
+            'npm run release:check'
+        ],
+        rollback_steps: [
+            'Revert only the files listed in the follow-up patch plan.',
+            'Restore package version metadata with npm install --package-lock-only if package-lock drift occurs.',
+            'Run npm run release:version-truth and the research blackbox gates after rollback.'
+        ],
+        parallel_work_decomposition: [
+            'WS-A stage runtime and research run integration.',
+            'WS-B source shards and ledger merge.',
+            'WS-C claim matrix builder.',
+            'WS-D blueprint and handoff densifier.',
+            'WS-E final reviewer.',
+            'WS-F blackbox gates and release DAG.',
+            'WS-G CLI/docs.',
+            'WS-H integration and verification.'
+        ],
+        sections,
+        dependencies: ['claim-evidence-matrix.json', 'source-ledger.json', 'falsification-ledger.json'],
+        out_of_scope: ['Repository source mutation during $Research runs.'],
+        open_questions: []
+    };
+}
+async function repositoryFileMap(root) {
+    const result = await runProcess('git', ['ls-files'], { cwd: root, timeoutMs: 15000, maxOutputBytes: 2 * 1024 * 1024 }).catch(() => ({ code: 1, stdout: '' }));
+    return String(result.stdout || '').split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+}
+function likelyTargetFiles(files, plan, claimMatrix) {
+    const promptTerms = new Set(String(plan?.prompt || '').toLowerCase().split(/[^a-z0-9]+/).filter((term) => term.length > 3));
+    const guidanceTerms = new Set((Array.isArray(claimMatrix?.claims) ? claimMatrix.claims : []).flatMap((claim) => String(claim?.claim || '').toLowerCase().split(/[^a-z0-9]+/)).filter((term) => term.length > 5));
+    const preferred = [
+        'src/core/research/research-cycle-runner.ts',
+        'src/core/research/research-stage-runner.ts',
+        'src/core/research/research-work-graph.ts',
+        'src/core/commands/research-command.ts',
+        'src/core/research/claim-evidence-matrix.ts',
+        'src/core/research/implementation-blueprint.ts',
+        'src/core/research/research-final-reviewer.ts',
+        'package.json',
+        'release-gates.v2.json',
+        'docs/research-pipeline.md',
+        'docs/research-artifacts.md',
+        'docs/research-implementation-handoff.md'
+    ].filter((file) => files.includes(file));
+    const matched = files.filter((file) => {
+        const lower = file.toLowerCase();
+        return lower.includes('research') || [...promptTerms, ...guidanceTerms].some((term) => lower.includes(term));
+    }).slice(0, 30);
+    return [...new Set([...preferred, ...matched])].slice(0, 40);
+}
+function possibleNewResearchFiles(files) {
+    return [
+        'src/core/research/research-source-shards.ts',
+        'src/core/research/research-source-ledger-merge.ts',
+        'src/core/research/research-claim-builder.ts',
+        'src/core/research/implementation-blueprint-densifier.ts',
+        'src/scripts/research-stage-cycle-runtime-blackbox.ts',
+        'src/scripts/research-short-report-rejection-check.ts',
+        'schemas/research/research-source-shard.schema.json'
+    ].filter((file) => !files.includes(file));
+}
+function section(id, title, detail, claimIds, targetPaths, acceptanceChecks) {
+    return {
+        id,
+        title,
+        order: ['problem', 'decision', 'architecture', 'interfaces', 'data_contracts', 'execution_plan', 'verification_plan', 'risks_and_rollbacks'].indexOf(id) + 1,
+        detail,
+        evidence_claim_ids: claimIds.slice(0, 8),
+        target_paths: targetPaths,
+        acceptance_checks: acceptanceChecks
+    };
+}
+function implementationSteps(existingFiles, newFiles) {
+    return [
+        `1. Update runtime files: ${existingFiles.filter((file) => file.includes('research-cycle-runner') || file.includes('research-stage-runner') || file.includes('research-work-graph')).join(', ')}.`,
+        `2. Add or verify source/claim/blueprint helper files: ${newFiles.filter((file) => file.includes('research')).join(', ')}.`,
+        '3. Wire sks research run so default execution uses runResearchCycle and the final.md Codex exec loop is legacy-only.',
+        '4. Add blackbox scripts that create temporary missions and verify rejection/pass/runtime behavior.',
+        '5. Update package scripts, release-gates.v2.json, docs, changelog, and version metadata.',
+        '6. Run the directive final checklist and record any hard blocker instead of claiming completion.'
+    ];
+}
+//# sourceMappingURL=implementation-blueprint-densifier.js.map

package/dist/core/research/research-claim-builder.js

@@ -0,0 +1,114 @@
+import { normalizeClaimEvidenceMatrix } from './claim-evidence-matrix.js';
+export async function buildClaimEvidenceMatrixFromSourceShards(input) {
+    const sources = [
+        ...(Array.isArray(input.sourceLedger?.sources) ? input.sourceLedger.sources : []),
+        ...(Array.isArray(input.sourceLedger?.counterevidence_sources) ? input.sourceLedger.counterevidence_sources : [])
+    ];
+    const noveltyEntries = Array.isArray(input.noveltyLedger?.entries) ? input.noveltyLedger.entries : [];
+    const candidates = new Map();
+    for (const entry of noveltyEntries) {
+        const id = String(entry?.id || '').trim();
+        if (!id)
+            continue;
+        candidates.set(id, {
+            id,
+            claim: String(entry?.claim || entry?.title || id),
+            claim_type: entry?.type === 'implementation_guidance' ? 'implementation_guidance' : 'hypothesis',
+            importance: candidates.size < 2 ? 'critical' : 'high',
+            source_ids: normalizeStringList(entry?.source_ids || entry?.evidence),
+            counterevidence_ids: normalizeStringList(entry?.counterevidence_ids || entry?.falsifiers),
+            test_or_probe: String(entry?.next_experiment || entry?.test_or_probe || '').trim()
+        });
+    }
+    for (const source of sources) {
+        const claimIds = normalizeStringList(source?.claim_ids);
+        if (claimIds.length) {
+            for (const claimId of claimIds) {
+                const existing = candidates.get(claimId) || {
+                    id: claimId,
+                    claim: claimTextFromSource(source, claimId),
+                    claim_type: 'inference',
+                    importance: candidates.size < 2 ? 'critical' : candidates.size < 8 ? 'high' : 'medium',
+                    source_ids: [],
+                    counterevidence_ids: [],
+                    test_or_probe: ''
+                };
+                if (source?.stance === 'undermines')
+                    existing.counterevidence_ids = [...new Set([...(existing.counterevidence_ids || []), source.id])];
+                else
+                    existing.source_ids = [...new Set([...(existing.source_ids || []), source.id])];
+                if (!existing.test_or_probe)
+                    existing.test_or_probe = `Probe ${claimId} against supporting and undermining source layers.`;
+                candidates.set(claimId, existing);
+            }
+        }
+        else if (String(source?.notes || '').trim()) {
+            const id = `hypothesis-${candidates.size + 1}`;
+            candidates.set(id, {
+                id,
+                claim: String(source.notes).slice(0, 240),
+                claim_type: 'hypothesis',
+                importance: 'medium',
+                source_ids: source?.stance === 'undermines' ? [] : [source.id].filter(Boolean),
+                counterevidence_ids: source?.stance === 'undermines' ? [source.id].filter(Boolean) : [],
+                test_or_probe: `Turn ${source.id || id} notes into a decisive source-backed probe.`
+            });
+        }
+    }
+    const falsificationCounterIds = new Set((Array.isArray(input.falsificationLedger?.cases) ? input.falsificationLedger.cases : [])
+        .flatMap((row) => [...normalizeStringList(row?.counterevidence_source_ids), ...normalizeStringList(row?.source_ids)]));
+    const claims = [...candidates.values()].slice(0, Math.max(8, candidates.size)).map((candidate, index) => {
+        const sourceIds = normalizeStringList(candidate.source_ids).filter((id) => sourceById(sources, id));
+        const counterIds = normalizeStringList(candidate.counterevidence_ids).filter((id) => sourceById(sources, id) || falsificationCounterIds.has(id));
+        const layers = sourceLayersForSourceIds(sources, [...sourceIds, ...counterIds]);
+        return {
+            id: candidate.id,
+            claim: candidate.claim,
+            claim_type: candidate.claim_type,
+            importance: candidate.importance || (index < 2 ? 'critical' : 'high'),
+            source_ids: sourceIds,
+            local_evidence_ids: sources.filter((source) => source.layer === 'local_project_evidence' && normalizeStringList(source.claim_ids).includes(candidate.id)).map((source) => source.id),
+            counterevidence_ids: counterIds,
+            triangulation: {
+                source_layers: layers,
+                independent_confirmation_count: layers.length,
+                conflicts: counterIds.length ? [`counterevidence:${counterIds.join(',')}`] : []
+            },
+            confidence: layers.length >= 3 && counterIds.length ? 'high' : layers.length >= 2 ? 'medium' : 'low',
+            falsifiable: true,
+            test_or_probe: candidate.test_or_probe || `Run a source-layer replication probe for ${candidate.id}.`
+        };
+    });
+    const unsupported = claims
+        .filter((claim) => {
+        const important = claim.importance === 'high' || claim.importance === 'critical';
+        return important && (claim.triangulation.source_layers.length < 2 || (claim.importance === 'critical' && claim.counterevidence_ids.length === 0));
+    })
+        .map((claim) => claim.id);
+    return normalizeClaimEvidenceMatrix({
+        schema: 'sks.claim-evidence-matrix.v1',
+        mission_id: input.plan?.mission_id || '',
+        claims,
+        key_claim_ids: claims.slice(0, 8).map((claim) => claim.id),
+        unsupported_claims: unsupported,
+        triangulated_claim_count: claims.filter((claim) => claim.triangulation.source_layers.length >= 2).length,
+        blockers: unsupported.map((id) => `unsupported_important_claim:${id}`)
+    });
+}
+function claimTextFromSource(source, claimId) {
+    const notes = String(source?.notes || '').trim();
+    if (notes)
+        return `${claimId}: ${notes.slice(0, 220)}`;
+    return `${claimId}: Evidence row ${source?.id || 'unknown'} contributes to this research claim.`;
+}
+function sourceById(sources, id) {
+    return sources.find((source) => String(source?.id || '') === id) || null;
+}
+function sourceLayersForSourceIds(sources, ids) {
+    const idSet = new Set(ids);
+    return [...new Set(sources.filter((source) => idSet.has(String(source?.id || ''))).map((source) => String(source?.layer || '')).filter(Boolean))];
+}
+function normalizeStringList(value) {
+    return [...new Set((Array.isArray(value) ? value : value == null ? [] : [value]).map((item) => String(item || '').trim()).filter(Boolean))];
+}
+//# sourceMappingURL=research-claim-builder.js.map

package/dist/core/research/research-cycle-runner.js

@@ -1,25 +1,129 @@
 import path from 'node:path';
 import { appendJsonlBounded, nowIso, writeJsonAtomic } from '../fsx.js';
 import { runResearchStage } from './research-stage-runner.js';
-export async function runResearchCycle(dir, graph = null, opts = {}) {
+export async function runResearchCycle(inputOrDir, legacyGraph = null, legacyOpts = {}) {
+    const input = typeof inputOrDir === 'string'
+        ? {
+            root: process.cwd(),
+            dir: inputOrDir,
+            plan: null,
+            graph: legacyGraph,
+            cycle: Number(legacyOpts.cycle || 0),
+            backend: legacyOpts.mock ? 'mock' : 'deterministic',
+            timeoutMs: Number(legacyOpts.timeoutMs || 120000),
+            maxParallelStages: Number(legacyOpts.maxParallelStages || legacyOpts.maxParallel || 4),
+            mock: legacyOpts.mock === true
+        }
+        : inputOrDir;
     const startedAt = nowIso();
-    const stages = Array.isArray(graph?.work_items) ? graph.work_items : [];
-    const stageResults = [];
-    for (const stage of stages) {
-        stageResults.push(await runResearchStage(dir, stage, { status: opts.status || 'planned', startedAt }));
+    const stages = normalizeStages(input.graph);
+    const pending = new Map(stages.map((stage) => [String(stage.id), stage]));
+    const completed = new Map();
+    const running = new Map();
+    const blockers = [];
+    const maxParallel = Math.max(1, Math.min(16, Number(input.maxParallelStages || 4)));
+    let maxObservedParallel = 0;
+    while (pending.size || running.size) {
+        const ready = readyStages([...pending.values()], completed);
+        while (running.size < maxParallel && ready.length) {
+            const stage = ready.shift();
+            if (!stage)
+                break;
+            pending.delete(String(stage.id));
+            const promise = runResearchStage({ ...input, stage }).catch((err) => failureStage(input, stage, err));
+            running.set(String(stage.id), promise);
+            maxObservedParallel = Math.max(maxObservedParallel, running.size);
+        }
+        if (!running.size) {
+            const blockedIds = [...pending.keys()];
+            blockers.push(...blockedIds.map((id) => `stage_dependencies_unresolved:${id}`));
+            for (const stage of pending.values()) {
+                const failed = failureStage(input, stage, new Error(`dependencies unresolved: ${(stage.dependencies || []).join(',')}`));
+                completed.set(String(stage.id), failed);
+            }
+            pending.clear();
+            break;
+        }
+        const done = await Promise.race([...running.entries()].map(async ([id, promise]) => ({ id, result: await promise })));
+        running.delete(done.id);
+        completed.set(done.id, done.result);
+        if (done.result.status !== 'passed' && pendingStageRequired(stages.find((stage) => String(stage.id) === done.id))) {
+            blockers.push(...(done.result.blockers.length ? done.result.blockers.map((blocker) => `${done.id}:${blocker}`) : [`${done.id}:stage_not_passed`]));
+        }
     }
+    const stageResults = [...completed.values()];
     const record = {
-        schema: 'sks.research-cycle-runner.v1',
-        cycle: opts.cycle || 0,
+        schema: 'sks.research-cycle-runner.v2',
+        cycle: input.cycle,
         readonly: true,
         started_at: startedAt,
         completed_at: nowIso(),
         stage_count: stageResults.length,
-        status: opts.status || 'planned',
-        stages: stageResults.map((stage) => stage.stage_id)
+        status: blockers.length ? 'blocked' : 'passed',
+        blockers: [...new Set(blockers)],
+        stages: stageResults.map((stage) => stage.stage_id),
+        stage_results: stageResults,
+        parallelism: {
+            max_parallel_stages: maxParallel,
+            max_observed_parallel: maxObservedParallel,
+            stage_count: stageResults.length,
+            critical_path_length: criticalPathLength(stages)
+        },
+        legacy_final_md_loop: false
     };
-    await writeJsonAtomic(path.join(dir, 'research-cycle-runner.json'), record);
-    await appendJsonlBounded(path.join(dir, 'events.jsonl'), { ts: nowIso(), type: 'research.cycle_runner.recorded', cycle: record.cycle, stage_count: record.stage_count });
+    await writeJsonAtomic(path.join(input.dir, 'research', `cycle-${input.cycle}`, 'research-cycle-runner.json'), record);
+    await writeJsonAtomic(path.join(input.dir, 'research-cycle-runner.json'), record);
+    await appendJsonlBounded(path.join(input.dir, 'events.jsonl'), { ts: nowIso(), type: 'research.cycle_runner.completed', cycle: record.cycle, stage_count: record.stage_count, status: record.status, max_observed_parallel: maxObservedParallel });
     return record;
 }
+export function readyStages(pending, completed) {
+    return pending.filter((stage) => (Array.isArray(stage.dependencies) ? stage.dependencies : []).every((id) => completed.has(String(id))));
+}
+function normalizeStages(graph) {
+    const stages = Array.isArray(graph?.work_items) ? graph.work_items : [];
+    return stages.map((stage, index) => ({
+        ...stage,
+        id: String(stage?.id || `research-stage-${index + 1}`),
+        dependencies: Array.isArray(stage?.dependencies) ? stage.dependencies.map(String) : []
+    }));
+}
+function pendingStageRequired(stage) {
+    return stage?.required !== false;
+}
+function failureStage(input, stage, err) {
+    const ts = nowIso();
+    return {
+        schema: 'sks.research-stage-result.v1',
+        mission_id: String(input.plan?.mission_id || ''),
+        cycle: input.cycle,
+        stage_id: String(stage?.id || 'unknown'),
+        stage_kind: 'verification',
+        status: 'failed',
+        started_at: ts,
+        completed_at: ts,
+        input_artifacts: [],
+        output_artifacts: [],
+        backend: input.backend,
+        worker_result_path: null,
+        blockers: [err instanceof Error ? err.message : String(err)],
+        metrics: {}
+    };
+}
+function criticalPathLength(stages) {
+    const byId = new Map(stages.map((stage) => [String(stage.id), stage]));
+    const memo = new Map();
+    const visit = (id, seen = new Set()) => {
+        if (memo.has(id))
+            return memo.get(id);
+        if (seen.has(id))
+            return 1;
+        seen.add(id);
+        const stage = byId.get(id);
+        const deps = Array.isArray(stage?.dependencies) ? stage.dependencies.map(String) : [];
+        const value = 1 + (deps.length ? Math.max(...deps.map((dep) => visit(dep, new Set(seen)))) : 0);
+        memo.set(id, value);
+        return value;
+    };
+    return stages.length ? Math.max(...stages.map((stage) => visit(String(stage.id)))) : 0;
+}
 //# sourceMappingURL=research-cycle-runner.js.map

package/dist/core/research/research-final-reviewer.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { nowIso, readJson, readText, writeJsonAtomic } from '../fsx.js';
+import { runCodexTask } from '../codex-control/codex-task-runner.js';
 import { analyzeResearchReportQuality } from './research-report-quality.js';
 import { validateClaimEvidenceMatrix } from './claim-evidence-matrix.js';
 import { validateImplementationBlueprint } from './implementation-blueprint.js';
@@ -7,10 +8,12 @@ import { validateExperimentPlan } from './experiment-plan.js';
 import { validateReplicationPack } from './replication-pack.js';
 import { validateFalsificationCoverage } from './falsification.js';
 export const RESEARCH_FINAL_REVIEW_ARTIFACT = 'research-final-review.json';
+export const RESEARCH_STATIC_FINAL_REVIEW_ARTIFACT = 'research-final-review.static.json';
+export const RESEARCH_CODEX_FINAL_REVIEW_ARTIFACT = 'research-final-review.codex.json';
 export async function readResearchFinalReview(dir) {
     return readJson(path.join(dir, RESEARCH_FINAL_REVIEW_ARTIFACT), null);
 }
-export async function runResearchFinalReviewer(dir, input = {}) {
+export async function runResearchStaticFinalReview(dir, input = {}) {
     const contract = input.contract || await readJson(path.join(dir, 'research-quality-contract.json'), null);
     const sourceLedger = input.sourceLedger || await readJson(path.join(dir, 'source-ledger.json'), null);
     const claimMatrix = input.claimMatrix || await readJson(path.join(dir, 'claim-evidence-matrix.json'), null);
@@ -52,7 +55,158 @@ export async function runResearchFinalReviewer(dir, input = {}) {
         },
         reviewer: 'research_final_reviewer_static_gate'
     };
+    await writeJsonAtomic(path.join(dir, RESEARCH_STATIC_FINAL_REVIEW_ARTIFACT), review);
+    return review;
+}
+export async function runResearchCodexFinalReviewer(input) {
+    if (input.staticReview?.approved !== true) {
+        const skipped = {
+            schema: 'sks.research-codex-final-review.v1',
+            reviewed_at: nowIso(),
+            verdict: 'revise',
+            unsupported_claim_ids: [],
+            missing_evidence: [],
+            blueprint_findings: [],
+            falsification_findings: [],
+            required_revisions: ['static_review_failed'],
+            confidence: 'low',
+            skipped: true,
+            skip_reason: 'static_review_failed'
+        };
+        await writeJsonAtomic(path.join(input.dir, RESEARCH_CODEX_FINAL_REVIEW_ARTIFACT), skipped);
+        return skipped;
+    }
+    if (input.mock === true) {
+        const approved = {
+            schema: 'sks.research-codex-final-review.v1',
+            reviewed_at: nowIso(),
+            verdict: 'approve',
+            unsupported_claim_ids: [],
+            missing_evidence: [],
+            blueprint_findings: ['mock final reviewer approves the complete package fixture'],
+            falsification_findings: ['mock counterevidence and falsification cases are present'],
+            required_revisions: [],
+            confidence: 'high',
+            mock: true
+        };
+        await writeJsonAtomic(path.join(input.dir, RESEARCH_CODEX_FINAL_REVIEW_ARTIFACT), approved);
+        return approved;
+    }
+    const result = await runCodexTask({
+        route: '$Research',
+        tier: 'worker',
+        missionId: String(input.plan?.mission_id || 'research-final-review'),
+        workItemId: 'research_final_review',
+        cwd: input.root,
+        prompt: buildResearchFinalReviewPrompt(input.plan, input.staticReview),
+        outputSchema: researchCodexFinalReviewSchema,
+        outputSchemaId: 'sks.research-codex-final-review.v1',
+        sandboxPolicy: 'read-only',
+        requestedScopeContract: {
+            id: 'research-final-review',
+            route: '$Research',
+            read_only: true,
+            allowed_paths: [`.sneakoscope/missions/${input.plan?.mission_id || ''}/`],
+            write_paths: [],
+            allowed_write_prefixes: [`.sneakoscope/missions/${input.plan?.mission_id || ''}/`],
+            source_mutation_allowed: false
+        },
+        backendPreference: input.backendPreference || ['codex-sdk', 'python-codex-sdk'],
+        localLlmPolicy: { mode: 'disabled', requiresGptFinal: true },
+        allowLocalLlm: false,
+        mutationLedgerRoot: path.join(input.dir, 'research', 'final-review-codex-control'),
+        reliabilityPolicy: {
+            timeoutClass: 'standard',
+            idleTimeoutMs: input.timeoutMs || 120000
+        }
+    });
+    const worker = await readJson(result.workerResultPath, null);
+    const review = normalizeCodexReview(worker, result);
+    await writeJsonAtomic(path.join(input.dir, RESEARCH_CODEX_FINAL_REVIEW_ARTIFACT), review);
+    return review;
+}
+export async function runResearchFinalReviewer(dir, input = {}) {
+    const staticReview = await runResearchStaticFinalReview(dir, input);
+    const existingCodex = await readJson(path.join(dir, RESEARCH_CODEX_FINAL_REVIEW_ARTIFACT), null);
+    const codexReview = existingCodex || (input.mock === true ? await runResearchCodexFinalReviewer({
+        root: input.root || process.cwd(),
+        dir,
+        plan: input.plan || await readJson(path.join(dir, 'research-plan.json'), null),
+        staticReview,
+        mock: true
+    }) : null);
+    const codexApproved = codexReview?.verdict === 'approve';
+    const codexRequired = input.codexRequired !== false;
+    const blockers = [
+        ...(Array.isArray(staticReview?.blockers) ? staticReview.blockers : []),
+        ...(codexRequired && !codexReview ? ['research_codex_final_review_missing'] : []),
+        ...(codexReview && !codexApproved ? ['research_codex_final_review_not_approved'] : []),
+        ...(Array.isArray(codexReview?.required_revisions) ? codexReview.required_revisions.map((revision) => `codex_revision:${revision}`) : [])
+    ];
+    const review = {
+        schema: 'sks.research-final-reviewer.v2',
+        reviewed_at: nowIso(),
+        approved: staticReview?.approved === true && (!codexRequired || codexApproved) && blockers.length === 0,
+        blockers: [...new Set(blockers)],
+        static_review: staticReview,
+        codex_review: codexReview,
+        reviewer: 'research_final_reviewer_static_plus_codex_gate'
+    };
     await writeJsonAtomic(path.join(dir, RESEARCH_FINAL_REVIEW_ARTIFACT), review);
     return review;
 }
+function buildResearchFinalReviewPrompt(plan, staticReview) {
+    return [
+        'You are the Codex/GPT final reviewer for an SKS Research package.',
+        `Mission: ${plan?.mission_id || 'unknown'}`,
+        `Prompt: ${plan?.prompt || ''}`,
+        '',
+        'Review the mission artifacts read-only. Reject if claims lack evidence, blueprint steps are template-like, falsification is missing, or the package is only a short summary.',
+        'Return only JSON matching sks.research-codex-final-review.v1 with verdict approve, revise, or reject.',
+        '',
+        `Static review summary:\n${JSON.stringify(staticReview, null, 2).slice(0, 12000)}`
+    ].join('\n');
+}
+function normalizeCodexReview(worker, result) {
+    if (!result?.ok) {
+        return {
+            schema: 'sks.research-codex-final-review.v1',
+            reviewed_at: nowIso(),
+            verdict: 'revise',
+            unsupported_claim_ids: [],
+            missing_evidence: [],
+            blueprint_findings: [],
+            falsification_findings: [],
+            required_revisions: Array.isArray(result?.blockers) ? result.blockers : ['codex_final_reviewer_unavailable'],
+            confidence: 'low',
+            worker_result_path: result?.workerResultPath || null
+        };
+    }
+    return {
+        schema: 'sks.research-codex-final-review.v1',
+        reviewed_at: nowIso(),
+        verdict: ['approve', 'revise', 'reject'].includes(worker?.verdict) ? worker.verdict : 'revise',
+        unsupported_claim_ids: Array.isArray(worker?.unsupported_claim_ids) ? worker.unsupported_claim_ids.map(String) : [],
+        missing_evidence: Array.isArray(worker?.missing_evidence) ? worker.missing_evidence.map(String) : [],
+        blueprint_findings: Array.isArray(worker?.blueprint_findings) ? worker.blueprint_findings.map(String) : [],
+        falsification_findings: Array.isArray(worker?.falsification_findings) ? worker.falsification_findings.map(String) : [],
+        required_revisions: Array.isArray(worker?.required_revisions) ? worker.required_revisions.map(String) : [],
+        confidence: ['low', 'medium', 'high'].includes(worker?.confidence) ? worker.confidence : 'medium',
+        worker_result_path: result.workerResultPath
+    };
+}
+export const researchCodexFinalReviewSchema = {
+    type: 'object',
+    required: ['schema', 'verdict', 'unsupported_claim_ids', 'missing_evidence', 'blueprint_findings', 'falsification_findings', 'required_revisions', 'confidence'],
+    properties: {
+        schema: { const: 'sks.research-codex-final-review.v1' },
+        verdict: { enum: ['approve', 'revise', 'reject'] },
+        unsupported_claim_ids: { type: 'array' },
+        missing_evidence: { type: 'array' },
+        blueprint_findings: { type: 'array' },
+        falsification_findings: { type: 'array' },
+        required_revisions: { type: 'array' },
+        confidence: { enum: ['low', 'medium', 'high'] }
+    }
+};
 //# sourceMappingURL=research-final-reviewer.js.map