sneakoscope 2.0.12 → 2.0.14

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

@@ -0,0 +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(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 = 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.v2',
+        cycle: input.cycle,
+        readonly: true,
+        started_at: startedAt,
+        completed_at: nowIso(),
+        stage_count: stageResults.length,
+        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(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

@@ -0,0 +1,212 @@
+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';
+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 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);
+    const blueprint = input.blueprint || await readJson(path.join(dir, 'implementation-blueprint.json'), null);
+    const experimentPlan = input.experimentPlan || await readJson(path.join(dir, 'experiment-plan.json'), null);
+    const replicationPack = input.replicationPack || await readJson(path.join(dir, 'replication-pack.json'), null);
+    const falsificationLedger = input.falsificationLedger || await readJson(path.join(dir, 'falsification-ledger.json'), null);
+    const reportText = input.reportText || await readText(path.join(dir, 'research-report.md'), '');
+    const claimValidation = validateClaimEvidenceMatrix(claimMatrix, sourceLedger, falsificationLedger);
+    const blueprintValidation = validateImplementationBlueprint(blueprint, contract);
+    const experimentValidation = validateExperimentPlan(experimentPlan, contract);
+    const replicationValidation = validateReplicationPack(replicationPack);
+    const falsificationValidation = validateFalsificationCoverage(falsificationLedger, contract);
+    const reportQuality = analyzeResearchReportQuality(reportText);
+    const preliminaryReasons = Array.isArray(input.preliminaryReasons) ? input.preliminaryReasons : [];
+    const blockers = [
+        ...preliminaryReasons,
+        ...claimValidation.blockers,
+        ...blueprintValidation.blockers,
+        ...experimentValidation.blockers,
+        ...replicationValidation.blockers,
+        ...falsificationValidation.blockers,
+        ...reportQuality.blockers
+    ];
+    const uniqueBlockers = [...new Set(blockers)];
+    const review = {
+        schema: 'sks.research-final-reviewer.v1',
+        reviewed_at: nowIso(),
+        approved: uniqueBlockers.length === 0,
+        blockers: uniqueBlockers,
+        contract_summary: contract || null,
+        checks: {
+            claim_matrix: claimValidation,
+            implementation_blueprint: blueprintValidation,
+            experiment_plan: experimentValidation,
+            replication_pack: replicationValidation,
+            falsification: falsificationValidation,
+            report_quality: reportQuality
+        },
+        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

package/dist/core/research/research-handoff.js

@@ -0,0 +1,51 @@
+import path from 'node:path';
+import { nowIso, writeJsonAtomic, writeTextAtomic } from '../fsx.js';
+export const IMPLEMENTATION_HANDOFF_PATCH_PLAN_ARTIFACT = 'implementation-handoff.patch-plan.json';
+export const TEAM_HANDOFF_GOAL_ARTIFACT = 'team-handoff-goal.md';
+export const DECISION_LOG_ARTIFACT = 'decision-log.md';
+export async function writeResearchHandoffArtifacts(dir, plan = null, blueprint = null) {
+    const patchPlan = {
+        schema: 'sks.research-implementation-handoff-patch-plan.v1',
+        generated_at: nowIso(),
+        mission_id: plan?.mission_id || null,
+        implementation_allowed_in_research: false,
+        intended_route: '$Team',
+        prompt: plan?.prompt || '',
+        source_artifacts: [
+            'research-report.md',
+            'claim-evidence-matrix.json',
+            'implementation-blueprint.json',
+            'experiment-plan.json',
+            'replication-pack.json',
+            'source-quality-report.json'
+        ],
+        proposed_changes: [],
+        notes: [
+            'This is a handoff artifact. Research records implementation guidance but does not mutate repository source.'
+        ]
+    };
+    const goalLines = [
+        '# Research-To-Team Handoff Goal',
+        '',
+        `Mission: ${plan?.mission_id || 'unknown'}`,
+        `Prompt: ${plan?.prompt || ''}`,
+        '',
+        'Use the implementation blueprint, claim-evidence matrix, source-quality report, experiment plan, replication pack, and final reviewer output before changing code.',
+        '',
+        'Blueprint sections:',
+        ...(Array.isArray(blueprint?.sections) ? blueprint.sections.map((section) => `- ${section.id}: ${section.title}`) : [])
+    ];
+    const decisionLog = [
+        '# Research Decision Log',
+        '',
+        `Created: ${nowIso()}`,
+        '',
+        '- Research may write route-local artifacts only.',
+        '- Implementation decisions must be revalidated in the follow-up execution route.'
+    ];
+    await writeJsonAtomic(path.join(dir, IMPLEMENTATION_HANDOFF_PATCH_PLAN_ARTIFACT), patchPlan);
+    await writeTextAtomic(path.join(dir, TEAM_HANDOFF_GOAL_ARTIFACT), `${goalLines.join('\n')}\n`);
+    await writeTextAtomic(path.join(dir, DECISION_LOG_ARTIFACT), `${decisionLog.join('\n')}\n`);
+    return { patch_plan: patchPlan, goal_artifact: TEAM_HANDOFF_GOAL_ARTIFACT, decision_log: DECISION_LOG_ARTIFACT };
+}
+//# sourceMappingURL=research-handoff.js.map

package/dist/core/research/research-prompt-contract.js

@@ -0,0 +1,24 @@
+export const RESEARCH_PROMPT_CONTRACT_LINES = Object.freeze([
+    'QUALITY CONTRACT: satisfy research-quality-contract.json before setting research-gate.json passed=true.',
+    'CLAIM MATRIX: create claim-evidence-matrix.json with key claims, source ids, counterevidence ids, triangulation, and hypothesis status.',
+    'SOURCE QUALITY: create source-quality-report.json and record claim_ids on source-ledger sources.',
+    'BLUEPRINT: create implementation-blueprint.json and implementation-blueprint.md with at least eight sections.',
+    'EXPERIMENT: create experiment-plan.json/.md with at least five steps and a replication-pack.json.',
+    'FINAL REVIEW: create research-final-review.json and keep the gate blocked unless approved=true.',
+    'READ ONLY: do not mutate repository source during Research; write only route-local mission artifacts.'
+]);
+export function researchPromptContractText() {
+    return RESEARCH_PROMPT_CONTRACT_LINES.join('\n');
+}
+export function validateResearchPromptContract(promptText = '') {
+    const text = String(promptText || '');
+    const requiredTokens = ['research-quality-contract.json', 'claim-evidence-matrix.json', 'source-quality-report.json', 'implementation-blueprint.json', 'experiment-plan.json', 'replication-pack.json', 'research-final-review.json'];
+    const missing = requiredTokens.filter((token) => !text.includes(token));
+    return {
+        ok: missing.length === 0,
+        blockers: missing.map((token) => `research_prompt_contract_missing:${token}`),
+        required_tokens: requiredTokens,
+        missing_tokens: missing
+    };
+}
+//# sourceMappingURL=research-prompt-contract.js.map

package/dist/core/research/research-quality-contract.js

@@ -0,0 +1,61 @@
+import path from 'node:path';
+import { readJson, writeJsonAtomic } from '../fsx.js';
+export const RESEARCH_QUALITY_CONTRACT_ARTIFACT = 'research-quality-contract.json';
+export const DEFAULT_RESEARCH_QUALITY_CONTRACT = {
+    schema: 'sks.research-quality-contract.v1',
+    min_sources_total: 12,
+    min_source_layers_covered: 5,
+    min_counterevidence_sources: 2,
+    min_trianguled_claims: 6,
+    min_key_claims: 8,
+    min_implementation_blueprint_sections: 8,
+    min_falsification_cases: 4,
+    min_experiment_steps: 5,
+    min_report_words: 2200,
+    required_artifacts: [
+        'research-report.md',
+        'implementation-blueprint.md',
+        'implementation-blueprint.json',
+        'claim-evidence-matrix.json',
+        'source-ledger.json',
+        'source-quality-report.json',
+        'falsification-ledger.json',
+        'experiment-plan.md',
+        'replication-pack.json',
+        'research-gate.json'
+    ]
+};
+export function normalizeResearchQualityContract(input = {}) {
+    const source = input && typeof input === 'object' ? input : {};
+    return {
+        ...DEFAULT_RESEARCH_QUALITY_CONTRACT,
+        ...source,
+        schema: 'sks.research-quality-contract.v1',
+        min_sources_total: positiveInt(source.min_sources_total, DEFAULT_RESEARCH_QUALITY_CONTRACT.min_sources_total),
+        min_source_layers_covered: positiveInt(source.min_source_layers_covered, DEFAULT_RESEARCH_QUALITY_CONTRACT.min_source_layers_covered),
+        min_counterevidence_sources: positiveInt(source.min_counterevidence_sources, DEFAULT_RESEARCH_QUALITY_CONTRACT.min_counterevidence_sources),
+        min_trianguled_claims: positiveInt(source.min_trianguled_claims ?? source.min_triangulated_claims, DEFAULT_RESEARCH_QUALITY_CONTRACT.min_trianguled_claims),
+        min_key_claims: positiveInt(source.min_key_claims, DEFAULT_RESEARCH_QUALITY_CONTRACT.min_key_claims),
+        min_implementation_blueprint_sections: positiveInt(source.min_implementation_blueprint_sections, DEFAULT_RESEARCH_QUALITY_CONTRACT.min_implementation_blueprint_sections),
+        min_falsification_cases: positiveInt(source.min_falsification_cases, DEFAULT_RESEARCH_QUALITY_CONTRACT.min_falsification_cases),
+        min_experiment_steps: positiveInt(source.min_experiment_steps, DEFAULT_RESEARCH_QUALITY_CONTRACT.min_experiment_steps),
+        min_report_words: positiveInt(source.min_report_words, DEFAULT_RESEARCH_QUALITY_CONTRACT.min_report_words),
+        required_artifacts: Array.isArray(source.required_artifacts) && source.required_artifacts.length
+            ? source.required_artifacts.map(String)
+            : [...DEFAULT_RESEARCH_QUALITY_CONTRACT.required_artifacts]
+    };
+}
+export async function readResearchQualityContract(dir) {
+    const contract = await readJson(path.join(dir, RESEARCH_QUALITY_CONTRACT_ARTIFACT), null);
+    return normalizeResearchQualityContract(contract || {});
+}
+export async function writeResearchQualityContract(dir, contract = {}) {
+    const normalized = normalizeResearchQualityContract(contract);
+    await writeJsonAtomic(path.join(dir, RESEARCH_QUALITY_CONTRACT_ARTIFACT), normalized);
+    return normalized;
+}
+function positiveInt(value, fallback) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+//# sourceMappingURL=research-quality-contract.js.map

package/dist/core/research/research-report-quality.js

@@ -0,0 +1,67 @@
+export const REQUIRED_RESEARCH_REPORT_HEADINGS = [
+    'Question',
+    'Methodology',
+    'Source Map',
+    'Key Claims',
+    'Evidence Matrix Summary',
+    'Counterevidence',
+    'Falsification',
+    'Implementation Blueprint',
+    'Experiment / Validation Plan',
+    'Limitations',
+    'References'
+];
+export function analyzeResearchReportQuality(text) {
+    const body = String(text || '');
+    const headings = body.split(/\r?\n/)
+        .map((line) => line.match(/^#{1,6}\s+(.+?)\s*#*\s*$/)?.[1]?.trim())
+        .filter((value) => Boolean(value));
+    const lowerHeadings = headings.map((heading) => normalizeHeading(heading));
+    const headingsPresent = REQUIRED_RESEARCH_REPORT_HEADINGS.filter((heading) => lowerHeadings.some((value) => value.includes(normalizeHeading(heading))));
+    const missingHeadings = REQUIRED_RESEARCH_REPORT_HEADINGS.filter((heading) => !headingsPresent.includes(heading));
+    const implementationText = sectionText(body, 'Implementation Blueprint');
+    const referencesText = sectionText(body, 'References');
+    const referencesSourceIds = [...new Set([
+            ...body.matchAll(/\b(?:source|src|mock-source|counter|mock-counter)-[A-Za-z0-9_.:-]+\b/g)
+        ].map((match) => match[0]))];
+    const blockers = [
+        ...missingHeadings.map((heading) => `research_report_heading_missing:${normalizeHeading(heading).replace(/\s+/g, '_')}`),
+        ...(referencesSourceIds.length ? [] : ['research_report_references_missing_source_ids'])
+    ];
+    return {
+        schema: 'sks.research-report-quality.v1',
+        word_count: countWords(body),
+        headings_present: headingsPresent,
+        missing_headings: missingHeadings,
+        implementation_section_words: countWords(implementationText),
+        references_source_ids: referencesText ? referencesSourceIds : [],
+        blockers,
+        ok: blockers.length === 0
+    };
+}
+export function countWords(text) {
+    return String(text || '').trim().split(/\s+/).filter(Boolean).length;
+}
+function normalizeHeading(value) {
+    return String(value || '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+}
+function sectionText(text, heading) {
+    const lines = String(text || '').split(/\r?\n/);
+    const target = normalizeHeading(heading);
+    let capture = false;
+    const out = [];
+    for (const line of lines) {
+        const match = line.match(/^(#{1,6})\s+(.+?)\s*#*\s*$/);
+        if (match) {
+            const normalized = normalizeHeading(match[2] || '');
+            if (capture)
+                break;
+            capture = normalized.includes(target);
+            continue;
+        }
+        if (capture)
+            out.push(line);
+    }
+    return out.join('\n');
+}
+//# sourceMappingURL=research-report-quality.js.map