sneakoscope 2.0.11 → 2.0.13

package/dist/core/research/claim-evidence-matrix.js

@@ -0,0 +1,160 @@
+import path from 'node:path';
+import { exists, nowIso, readJson, writeJsonAtomic } from '../fsx.js';
+export const CLAIM_EVIDENCE_MATRIX_ARTIFACT = 'claim-evidence-matrix.json';
+export function defaultClaimEvidenceMatrix(missionId = '') {
+    return {
+        schema: 'sks.claim-evidence-matrix.v1',
+        mission_id: missionId,
+        claims: [],
+        key_claim_ids: [],
+        unsupported_claims: [],
+        triangulated_claim_count: 0,
+        blockers: []
+    };
+}
+export async function readClaimEvidenceMatrix(dir) {
+    const file = path.join(dir, CLAIM_EVIDENCE_MATRIX_ARTIFACT);
+    const present = await exists(file);
+    const matrix = normalizeClaimEvidenceMatrix(await readJson(file, null));
+    return {
+        present,
+        matrix,
+        key_claim_ids: matrix.key_claim_ids,
+        unsupported_claims: matrix.unsupported_claims,
+        triangulated_claim_count: matrix.triangulated_claim_count,
+        blockers: present ? matrix.blockers : ['claim_evidence_matrix_missing']
+    };
+}
+export async function writeClaimEvidenceMatrix(dir, matrix) {
+    const normalized = normalizeClaimEvidenceMatrix(matrix);
+    await writeJsonAtomic(path.join(dir, CLAIM_EVIDENCE_MATRIX_ARTIFACT), normalized);
+    return normalized;
+}
+export function validateClaimEvidenceMatrix(matrix, sourceLedger = null, falsificationLedger = null) {
+    const normalized = normalizeClaimEvidenceMatrix(matrix);
+    const claimIds = new Set(normalized.claims.map((claim) => claim.id));
+    const sourceIds = sourceIdSet(sourceLedger);
+    const counterIds = new Set([
+        ...Array.from(sourceIds).filter((id) => /counter/i.test(id)),
+        ...(Array.isArray(sourceLedger?.counterevidence_sources) ? sourceLedger.counterevidence_sources.map((row) => String(row?.id || '')).filter(Boolean) : []),
+        ...(Array.isArray(falsificationLedger?.cases) ? falsificationLedger.cases.flatMap((row) => [row?.id, ...(Array.isArray(row?.counterevidence_source_ids) ? row.counterevidence_source_ids : []), ...(Array.isArray(row?.source_ids) ? row.source_ids : [])]).map(String).filter(Boolean) : [])
+    ]);
+    const blockers = [];
+    for (const id of normalized.key_claim_ids)
+        if (!claimIds.has(id))
+            blockers.push(`key_claim_missing:${id}`);
+    for (const claim of normalized.claims) {
+        const important = claim.importance === 'high' || claim.importance === 'critical';
+        if (important && !claim.source_ids.length)
+            blockers.push(`claim_source_missing:${claim.id}`);
+        if (claim.importance === 'critical' && !claim.counterevidence_ids.length)
+            blockers.push(`critical_claim_counterevidence_missing:${claim.id}`);
+        for (const sourceId of claim.source_ids)
+            if (!sourceIds.has(sourceId))
+                blockers.push(`claim_source_unknown:${claim.id}:${sourceId}`);
+        for (const counterId of claim.counterevidence_ids)
+            if (!counterIds.has(counterId))
+                blockers.push(`claim_counterevidence_unknown:${claim.id}:${counterId}`);
+        if (claim.claim_type === 'hypothesis' && !claim.test_or_probe.trim())
+            blockers.push(`hypothesis_probe_missing:${claim.id}`);
+    }
+    for (const id of normalized.unsupported_claims) {
+        const claim = normalized.claims.find((row) => row.id === id);
+        if (claim?.importance === 'high' || claim?.importance === 'critical')
+            blockers.push(`unsupported_important_claim:${id}`);
+    }
+    return { ok: blockers.length === 0, blockers: [...new Set(blockers)] };
+}
+export function normalizeClaimEvidenceMatrix(value) {
+    const raw = value && typeof value === 'object' ? value : {};
+    const claims = (Array.isArray(raw.claims) ? raw.claims : []).map(normalizeClaim).filter((claim) => claim.id);
+    const keyClaimIds = normalizeStringList(raw.key_claim_ids).filter((id) => claims.some((claim) => claim.id === id));
+    const unsupported = normalizeStringList(raw.unsupported_claims);
+    return {
+        schema: 'sks.claim-evidence-matrix.v1',
+        mission_id: String(raw.mission_id || ''),
+        claims,
+        key_claim_ids: keyClaimIds,
+        unsupported_claims: unsupported,
+        triangulated_claim_count: Number.isFinite(Number(raw.triangulated_claim_count))
+            ? Math.max(0, Math.floor(Number(raw.triangulated_claim_count)))
+            : claims.filter((claim) => claim.triangulation.independent_confirmation_count >= 2 && claim.triangulation.source_layers.length >= 2).length,
+        blockers: normalizeStringList(raw.blockers)
+    };
+}
+export function buildClaimEvidenceMatrixFromLedgers(input = {}) {
+    const entries = Array.isArray(input.noveltyLedger?.entries) ? input.noveltyLedger.entries : [];
+    const sources = Array.isArray(input.sourceLedger?.sources) ? input.sourceLedger.sources : [];
+    const counterSources = Array.isArray(input.sourceLedger?.counterevidence_sources) ? input.sourceLedger.counterevidence_sources : [];
+    const fallbackSourceIds = sources.map((row) => String(row?.id || '')).filter(Boolean);
+    const fallbackCounterIds = counterSources.map((row) => String(row?.id || '')).filter(Boolean);
+    const claims = entries.map((entry, index) => {
+        const id = String(entry.id || `claim-${index + 1}`);
+        const sourceIds = normalizeStringList(entry.source_ids || entry.evidence).filter((sourceId) => fallbackSourceIds.includes(sourceId));
+        const counterIds = normalizeStringList(entry.counterevidence_ids || entry.falsifiers).filter((sourceId) => fallbackCounterIds.includes(sourceId));
+        return normalizeClaim({
+            id,
+            claim: entry.claim || entry.title || id,
+            claim_type: 'hypothesis',
+            importance: index < 2 ? 'critical' : 'high',
+            source_ids: sourceIds.length ? sourceIds : fallbackSourceIds.slice(0, 2),
+            counterevidence_ids: counterIds.length ? counterIds : fallbackCounterIds.slice(0, 1),
+            triangulation: {
+                source_layers: sourceLayersForSourceIds(input.sourceLedger, sourceIds.length ? sourceIds : fallbackSourceIds),
+                independent_confirmation_count: Math.max(1, sourceIds.length || fallbackSourceIds.length),
+                conflicts: []
+            },
+            confidence: entry.confidence >= 2 ? 'high' : 'medium',
+            falsifiable: true,
+            test_or_probe: entry.next_experiment || entry.test_or_probe || 'Run the proposed replication probe.'
+        });
+    });
+    return normalizeClaimEvidenceMatrix({
+        schema: 'sks.claim-evidence-matrix.v1',
+        mission_id: input.missionId || '',
+        claims,
+        key_claim_ids: claims.slice(0, 8).map((claim) => claim.id),
+        unsupported_claims: [],
+        triangulated_claim_count: claims.filter((claim) => claim.triangulation.source_layers.length >= 2).length,
+        blockers: []
+    });
+}
+function normalizeClaim(value) {
+    const importance = ['low', 'medium', 'high', 'critical'].includes(value?.importance) ? value.importance : 'medium';
+    const claimType = ['fact', 'inference', 'hypothesis', 'recommendation', 'implementation_guidance'].includes(value?.claim_type) ? value.claim_type : 'hypothesis';
+    const confidence = ['low', 'medium', 'high'].includes(value?.confidence) ? value.confidence : 'medium';
+    return {
+        id: String(value?.id || '').trim(),
+        claim: String(value?.claim || '').trim(),
+        claim_type: claimType,
+        importance,
+        source_ids: normalizeStringList(value?.source_ids),
+        local_evidence_ids: normalizeStringList(value?.local_evidence_ids),
+        counterevidence_ids: normalizeStringList(value?.counterevidence_ids),
+        triangulation: {
+            source_layers: normalizeStringList(value?.triangulation?.source_layers),
+            independent_confirmation_count: Math.max(0, Math.floor(Number(value?.triangulation?.independent_confirmation_count || 0))),
+            conflicts: normalizeStringList(value?.triangulation?.conflicts)
+        },
+        confidence,
+        falsifiable: value?.falsifiable !== false,
+        test_or_probe: String(value?.test_or_probe || '').trim()
+    };
+}
+function sourceIdSet(sourceLedger) {
+    return new Set([
+        ...(Array.isArray(sourceLedger?.sources) ? sourceLedger.sources : []),
+        ...(Array.isArray(sourceLedger?.counterevidence_sources) ? sourceLedger.counterevidence_sources : [])
+    ].map((row) => String(row?.id || '')).filter(Boolean));
+}
+function sourceLayersForSourceIds(sourceLedger, ids) {
+    const idSet = new Set(ids);
+    return [...new Set([
+            ...(Array.isArray(sourceLedger?.sources) ? sourceLedger.sources : []),
+            ...(Array.isArray(sourceLedger?.counterevidence_sources) ? sourceLedger.counterevidence_sources : [])
+        ].filter((row) => idSet.has(String(row?.id || ''))).map((row) => String(row?.layer || row?.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=claim-evidence-matrix.js.map

package/dist/core/research/experiment-plan.js

@@ -0,0 +1,53 @@
+import path from 'node:path';
+import { nowIso, readJson, writeJsonAtomic, writeTextAtomic } from '../fsx.js';
+export const EXPERIMENT_PLAN_JSON_ARTIFACT = 'experiment-plan.json';
+export const EXPERIMENT_PLAN_MARKDOWN_ARTIFACT = 'experiment-plan.md';
+export function defaultExperimentPlan(plan = null) {
+    const prompt = String(plan?.prompt || 'research mission');
+    return {
+        schema: 'sks.research-experiment-plan.v1',
+        generated_at: nowIso(),
+        prompt,
+        hypothesis: 'The surviving research claim should produce a measurable improvement over a summary-only baseline.',
+        steps: [
+            { id: 'E1', action: 'Select one baseline output and one research-pipeline output for the same prompt.', expected_evidence: ['research-report.md'] },
+            { id: 'E2', action: 'Score cited key claims, triangulation, counterevidence, and unsupported claims.', expected_evidence: ['claim-evidence-matrix.json'] },
+            { id: 'E3', action: 'Run or design the smallest probe implied by the implementation blueprint.', expected_evidence: ['implementation-blueprint.json'] },
+            { id: 'E4', action: 'Compare failure cases and falsification outcomes.', expected_evidence: ['falsification-ledger.json'] },
+            { id: 'E5', action: 'Record replication commands, artifacts, and acceptance thresholds.', expected_evidence: ['replication-pack.json'] }
+        ],
+        metrics: ['key_claims_supported', 'triangulated_claims', 'counterevidence_sources', 'falsification_cases', 'experiment_steps'],
+        controls: ['summary_only_baseline', 'same_prompt_same_context'],
+        acceptance_threshold: 'All quality-contract thresholds are met and the final reviewer approves the run.'
+    };
+}
+export function validateExperimentPlan(experimentPlan = null, contract = null) {
+    const minSteps = Number(contract?.min_experiment_steps || 5);
+    const steps = Array.isArray(experimentPlan?.steps) ? experimentPlan.steps : [];
+    const completeSteps = steps.filter((step) => String(step?.id || '').trim() && String(step?.action || '').trim());
+    const blockers = [
+        ...(experimentPlan ? [] : ['experiment_plan_missing']),
+        ...(steps.length < minSteps ? ['experiment_plan_steps_below_contract'] : []),
+        ...(completeSteps.length < minSteps ? ['experiment_plan_too_thin'] : [])
+    ];
+    return { ok: blockers.length === 0, blockers, steps: steps.length, complete_steps: completeSteps.length, min_steps: minSteps };
+}
+export function renderExperimentPlanMarkdown(experimentPlan = null) {
+    const lines = ['# Research Experiment Plan', '', `Hypothesis: ${experimentPlan?.hypothesis || ''}`, '', '## Steps'];
+    for (const step of Array.isArray(experimentPlan?.steps) ? experimentPlan.steps : []) {
+        lines.push(`- ${step.id}: ${step.action}`);
+    }
+    lines.push('', '## Metrics');
+    for (const metric of Array.isArray(experimentPlan?.metrics) ? experimentPlan.metrics : [])
+        lines.push(`- ${metric}`);
+    return `${lines.join('\n')}\n`;
+}
+export async function readExperimentPlan(dir) {
+    return readJson(path.join(dir, EXPERIMENT_PLAN_JSON_ARTIFACT), null);
+}
+export async function writeExperimentPlan(dir, experimentPlan) {
+    await writeJsonAtomic(path.join(dir, EXPERIMENT_PLAN_JSON_ARTIFACT), experimentPlan);
+    await writeTextAtomic(path.join(dir, EXPERIMENT_PLAN_MARKDOWN_ARTIFACT), renderExperimentPlanMarkdown(experimentPlan));
+    return experimentPlan;
+}
+//# sourceMappingURL=experiment-plan.js.map

package/dist/core/research/falsification.js

@@ -0,0 +1,18 @@
+export function validateFalsificationCoverage(falsificationLedger = null, contract = null) {
+    const minCases = Number(contract?.min_falsification_cases || 4);
+    const cases = Array.isArray(falsificationLedger?.cases) ? falsificationLedger.cases : [];
+    const completeCases = cases.filter((entry) => {
+        return String(entry?.id || '').trim()
+            && String(entry?.target_claim || entry?.claim_id || '').trim()
+            && String(entry?.attack || entry?.counterexample || '').trim()
+            && Array.isArray(entry?.source_ids)
+            && entry.source_ids.length > 0
+            && String(entry?.next_decisive_test || '').trim();
+    });
+    const blockers = [
+        ...(cases.length < minCases ? ['falsification_cases_below_contract'] : []),
+        ...(completeCases.length < minCases ? ['falsification_cases_incomplete'] : [])
+    ];
+    return { ok: blockers.length === 0, blockers, cases: cases.length, complete_cases: completeCases.length, min_cases: minCases };
+}
+//# sourceMappingURL=falsification.js.map

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

@@ -0,0 +1,31 @@
+export const IMPLEMENTATION_BLUEPRINT_MARKDOWN_ARTIFACT = 'implementation-blueprint.md';
+export function renderImplementationBlueprintMarkdown(blueprint = null) {
+    const lines = [];
+    lines.push('# Research Implementation Blueprint');
+    lines.push('');
+    lines.push(`Prompt: ${blueprint?.prompt || ''}`);
+    lines.push(`Handoff route: ${blueprint?.handoff_route || '$Team'}`);
+    lines.push(`Implementation allowed in Research: ${blueprint?.implementation_allowed_in_research === true ? 'yes' : 'no'}`);
+    lines.push('');
+    lines.push('## Sections');
+    for (const section of Array.isArray(blueprint?.sections) ? blueprint.sections : []) {
+        lines.push(`### ${section.title || section.id}`);
+        lines.push('');
+        lines.push(String(section.detail || ''));
+        if (Array.isArray(section.acceptance_checks) && section.acceptance_checks.length) {
+            lines.push('');
+            lines.push('Acceptance checks:');
+            for (const check of section.acceptance_checks)
+                lines.push(`- ${check}`);
+        }
+        lines.push('');
+    }
+    if (Array.isArray(blueprint?.risks) && blueprint.risks.length) {
+        lines.push('## Risks');
+        for (const risk of blueprint.risks)
+            lines.push(`- ${risk}`);
+        lines.push('');
+    }
+    return `${lines.join('\n')}\n`;
+}
+//# sourceMappingURL=implementation-blueprint-markdown.js.map

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

@@ -0,0 +1,66 @@
+import path from 'node:path';
+import { nowIso, readJson, writeJsonAtomic } from '../fsx.js';
+export const IMPLEMENTATION_BLUEPRINT_ARTIFACT = 'implementation-blueprint.json';
+const DEFAULT_SECTION_IDS = Object.freeze([
+    'problem',
+    'decision',
+    'architecture',
+    'interfaces',
+    'data_contracts',
+    'execution_plan',
+    'verification_plan',
+    'risks_and_rollbacks'
+]);
+export function defaultImplementationBlueprint(plan = null) {
+    const prompt = String(plan?.prompt || 'research mission');
+    return {
+        schema: 'sks.research-implementation-blueprint.v1',
+        generated_at: nowIso(),
+        prompt,
+        implementation_allowed_in_research: false,
+        handoff_route: '$Team',
+        sections: DEFAULT_SECTION_IDS.map((id, index) => ({
+            id,
+            title: id.split('_').map((part) => part[0]?.toUpperCase() + part.slice(1)).join(' '),
+            order: index + 1,
+            detail: `Research handoff detail for ${id} on: ${prompt}`,
+            evidence_claim_ids: [],
+            target_paths: [],
+            acceptance_checks: [`${id} is reviewed against cited research artifacts before implementation.`]
+        })),
+        dependencies: [],
+        out_of_scope: ['Repository source mutation during $Research runs.'],
+        open_questions: []
+    };
+}
+export function validateImplementationBlueprint(blueprint = null, contract = null) {
+    const minSections = Number(contract?.min_implementation_blueprint_sections || contract?.min_blueprint_sections || 8);
+    const sections = Array.isArray(blueprint?.sections) ? blueprint.sections : [];
+    const completeSections = sections.filter((section) => {
+        return String(section?.id || '').trim()
+            && String(section?.title || '').trim()
+            && String(section?.detail || '').trim()
+            && Array.isArray(section?.acceptance_checks)
+            && section.acceptance_checks.length > 0;
+    });
+    const blockers = [
+        ...(blueprint ? [] : ['implementation_blueprint_missing']),
+        ...(sections.length < minSections ? ['implementation_blueprint_sections_below_contract'] : []),
+        ...(completeSections.length < minSections ? ['implementation_blueprint_incomplete_sections'] : [])
+    ];
+    return {
+        ok: blockers.length === 0,
+        blockers,
+        sections: sections.length,
+        complete_sections: completeSections.length,
+        min_sections: minSections
+    };
+}
+export async function readImplementationBlueprint(dir) {
+    return readJson(path.join(dir, IMPLEMENTATION_BLUEPRINT_ARTIFACT), null);
+}
+export async function writeImplementationBlueprint(dir, blueprint) {
+    await writeJsonAtomic(path.join(dir, IMPLEMENTATION_BLUEPRINT_ARTIFACT), blueprint);
+    return blueprint;
+}
+//# sourceMappingURL=implementation-blueprint.js.map

package/dist/core/research/replication-pack.js

@@ -0,0 +1,50 @@
+import path from 'node:path';
+import { nowIso, readJson, writeJsonAtomic } from '../fsx.js';
+export const REPLICATION_PACK_ARTIFACT = 'replication-pack.json';
+export function defaultReplicationPack(plan = null) {
+    return {
+        schema: 'sks.research-replication-pack.v1',
+        generated_at: nowIso(),
+        mission_id: plan?.mission_id || null,
+        prompt: plan?.prompt || '',
+        inputs: ['research-plan.json', 'research-quality-contract.json', 'source-ledger.json', 'claim-evidence-matrix.json'],
+        commands: [
+            'sks research status latest',
+            'npm run research:quality-contract',
+            'npm run research:claim-matrix',
+            'npm run research:final-review'
+        ],
+        expected_artifacts: [
+            'research-report.md',
+            'claim-evidence-matrix.json',
+            'source-quality-report.json',
+            'implementation-blueprint.json',
+            'experiment-plan.json',
+            'replication-pack.json',
+            'research-final-review.json',
+            'research-gate.evaluated.json'
+        ],
+        assumptions: ['Live source retrieval must be recorded in source-ledger.json for real runs.'],
+        reproduction_notes: []
+    };
+}
+export function validateReplicationPack(replicationPack = null) {
+    const commands = Array.isArray(replicationPack?.commands) ? replicationPack.commands : [];
+    const artifacts = Array.isArray(replicationPack?.expected_artifacts) ? replicationPack.expected_artifacts : [];
+    const inputs = Array.isArray(replicationPack?.inputs) ? replicationPack.inputs : [];
+    const blockers = [
+        ...(replicationPack ? [] : ['replication_pack_missing']),
+        ...(commands.length < 3 ? ['replication_pack_commands_too_thin'] : []),
+        ...(artifacts.length < 6 ? ['replication_pack_artifacts_too_thin'] : []),
+        ...(inputs.length < 3 ? ['replication_pack_inputs_too_thin'] : [])
+    ];
+    return { ok: blockers.length === 0, blockers, commands: commands.length, artifacts: artifacts.length, inputs: inputs.length };
+}
+export async function readReplicationPack(dir) {
+    return readJson(path.join(dir, REPLICATION_PACK_ARTIFACT), null);
+}
+export async function writeReplicationPack(dir, replicationPack) {
+    await writeJsonAtomic(path.join(dir, REPLICATION_PACK_ARTIFACT), replicationPack);
+    return replicationPack;
+}
+//# sourceMappingURL=replication-pack.js.map

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

@@ -0,0 +1,25 @@
+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 = {}) {
+    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 record = {
+        schema: 'sks.research-cycle-runner.v1',
+        cycle: opts.cycle || 0,
+        readonly: true,
+        started_at: startedAt,
+        completed_at: nowIso(),
+        stage_count: stageResults.length,
+        status: opts.status || 'planned',
+        stages: stageResults.map((stage) => stage.stage_id)
+    };
+    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 });
+    return record;
+}
+//# sourceMappingURL=research-cycle-runner.js.map

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

@@ -0,0 +1,58 @@
+import path from 'node:path';
+import { nowIso, readJson, readText, writeJsonAtomic } from '../fsx.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 async function readResearchFinalReview(dir) {
+    return readJson(path.join(dir, RESEARCH_FINAL_REVIEW_ARTIFACT), null);
+}
+export async function runResearchFinalReviewer(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_FINAL_REVIEW_ARTIFACT), review);
+    return review;
+}
+//# 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