sneakoscope 2.0.12 → 2.0.14

package/dist/core/pipeline/final-gpt-patch-stage.js

@@ -5,17 +5,18 @@ export function selectFinalGptPatchSource(gptFinal, localPatchEnvelopes = []) {
             schema: 'sks.final-gpt-patch-stage.v1',
             ok: true,
             final_patch_source: 'gpt_final_arbiter',
-            patch_envelopes: Array.isArray(gptFinal?.result?.modified_patch_envelopes) ? gptFinal.result.modified_patch_envelopes : [],
+            patch_envelopes: decodePatchDecisionItems(gptFinal?.result?.modified_patch_envelopes),
             blockers: []
         };
     }
     if (status === 'approved') {
+        const accepted = decodePatchDecisionItems(gptFinal?.result?.accepted_patch_envelopes);
         return {
             schema: 'sks.final-gpt-patch-stage.v1',
             ok: true,
             final_patch_source: 'gpt_final_arbiter',
-            patch_envelopes: Array.isArray(gptFinal?.result?.accepted_patch_envelopes) && gptFinal.result.accepted_patch_envelopes.length
-                ? gptFinal.result.accepted_patch_envelopes
+            patch_envelopes: accepted.length
+                ? accepted
                 : localPatchEnvelopes,
             blockers: []
         };
@@ -28,4 +29,20 @@ export function selectFinalGptPatchSource(gptFinal, localPatchEnvelopes = []) {
         blockers: ['gpt_final_not_approved']
     };
 }
+function decodePatchDecisionItems(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((entry) => {
+        if (entry && typeof entry === 'object' && typeof entry.patch_envelope_json === 'string') {
+            try {
+                const parsed = JSON.parse(entry.patch_envelope_json);
+                return parsed && typeof parsed === 'object' && Object.keys(parsed).length ? [parsed] : [];
+            }
+            catch {
+                return [];
+            }
+        }
+        return entry && typeof entry === 'object' ? [entry] : [];
+    });
+}
 //# sourceMappingURL=final-gpt-patch-stage.js.map

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-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/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