sneakoscope 2.0.12 → 2.0.13

package/README.md

@@ -16,7 +16,7 @@ Set up this agent project with Sneakoscope Codex. Use [[mandarange/Sneakoscope-C
 
 ## Current Release
 
-SKS **2.0.12** is the public-ready parallel runtime stabilization release. It closes release DAG coverage around Zellij slot renderer proof semantics, wires Naruto allocation/rebalance into the production scheduler, keeps pre-run worker smoke opt-in, and requires GPT Final approval before local/worktree candidate output can apply.
+SKS **2.0.13** is the public-ready research pipeline stabilization release. It closes the Research quality contract, claim-evidence matrix, source-quality report, implementation handoff, experiment/replication pack, final-reviewer, and read-only stage-aware work graph path while preserving the 2.0.12 parallel runtime stabilization work.
 
 What changed:
 
@@ -466,6 +466,8 @@ sks code-structure scan --json
 
 `sks research` prepares a named genius-lens agent council, requires every agent to run at `xhigh`, records one literal `Eureka!` idea per agent, runs an evidence-bound debate, and creates `research-source-skill.md` as a route-local source collection skill before synthesis. Research is not a code-change route: real runs may write only their own mission artifacts under `.sneakoscope/missions/<id>/`, and source/package/docs/config mutations block the run with `research-code-mutation-blocker.json`. The required Research persona lenses are Einstein Agent, Feynman Agent, Turing Agent, von Neumann Agent, and Skeptic Agent; they are cognitive roles, not impersonations, and `agent-ledger.json` must include `display_name`, `persona`, `persona_boundary`, `reasoning_effort`, falsifiers, cheap probes, and `challenge_or_response`. Normal Research is not a fixed three-cycle flow: it repeats source gathering, Eureka ideas, debate, falsification, and synthesis pressure until every agent records final agreement, or pauses at the explicit max-cycle safety cap with an unpassed gate. `debate-ledger.json` must include `consensus_iterations`, `unanimous_consensus`, and per-agent agreements; `research-gate.json` cannot pass until unanimous consensus is true for all agents. Normal Research is intentionally allowed to take one or two hours when the problem needs it; `--mock` is only for selftests or dry harness checks, and a real run blocks with `research-blocker.json` instead of silently substituting mock output when the Codex execution path is unavailable. The source layer contract separates latest papers, official/government or leading-institution sources, standards/primary docs, current news such as BBC/CNN/GDELT-style sources, public discourse such as X/Reddit, developer/practitioner knowledge such as Stack Overflow/GitHub, traditional background sources, and counterevidence/fact-checking; `source-ledger.json` must record layer coverage, source quality, blockers, citations, and cross-layer triangulation. Context7 is optional for `$Research` and only becomes relevant when the research topic specifically depends on package, API, framework, or SDK documentation. Research runs require `research-report.md`, `research-paper.md`, `genius-opinion-summary.md`, `research-source-skill.md`, `source-ledger.json`, `agent-ledger.json`, `debate-ledger.json`, `novelty-ledger.json`, `falsification-ledger.json`, and `research-gate.json` so they stay source-backed, adversarially checked, falsifiable, paper-ready, and clear about every agent lens opinion. `research status` reports source entries, source-layer coverage, triangulation checks, counterevidence, xhigh agent count, Eureka moments, debate exchanges, consensus iterations, unanimous consensus, paper presence/sections, genius-opinion summary coverage, agent findings, and falsification cases alongside the gate.
 
+In 2.0.13, Research also writes a quality contract and handoff package: `research-quality-contract.json`, `claim-evidence-matrix.json`, `source-quality-report.json`, `implementation-blueprint.json`/`.md`, `experiment-plan.json`/`.md`, `replication-pack.json`, `research-work-graph.json`, and `research-final-review.json`. The default gate requires 12 total sources, 5 source layers, 2 counterevidence sources, 8 key claims, 6 triangulated claims, 8 blueprint sections, 4 falsification cases, 5 experiment steps, and a 2200-word report before `research-gate.json` can pass. See `docs/research-pipeline.md`, `docs/research-artifacts.md`, and `docs/research-implementation-handoff.md`.
+
 `sks recallpulse` is the 0.8.0 report-only RecallPulse utility. It writes `recallpulse-decision.json`, `mission-status-ledger.json`, `route-proof-capsule.json`, `evidence-envelope.json`, `recallpulse-governance-report.json`, `recallpulse-task-goal-ledger.json`, and `recallpulse-eval-report.json` for the current mission. RecallPulse does not replace route gates, Honest Mode, DB safety, imagegen evidence, or TriWiki validation; it records cache hits, hydration needs, duplicate suppression, route-governance risks, and final-summary-ready durable status so later releases can promote only measured improvements. Checklist updates are sequential: every `Txxx` row is treated as a child `$Goal` checkpoint, and `sks recallpulse checklist ... --task T001 --apply` refuses out-of-order checks unless explicitly overridden.
 
 `sks pipeline plan` shows the active route lane, kept/skipped stages, verification commands, and no-unrequested-fallback invariant. The 0.9.0 Decision Lattice augments this planning surface with report-only A*/proof-debt evidence: frontier paths considered, the selected path, and rejected paths with rejection reasons. `sks proof-field scan` remains the lightweight rubric for small changes; risky or broad signals return to the full Team/Honest path, and no speedup claim is valid without replay or eval evidence.
@@ -531,6 +533,8 @@ $DB inspect this migration for destructive risk
 
 Local model workers are off by default, so SKS stays GPT-only unless you explicitly enable them. Use the Codex App prompt commands:
 
+![SKS Local LLM mode workflow](docs/sks-local-llm-mode/assets/sks-local-llm-flow.png)
+
 ```text
 $with-local-llm-on
 $with-local-llm-off

package/crates/sks-core/Cargo.lock

@@ -76,7 +76,7 @@ dependencies = [
 
 [[package]]
 name = "sks-core"
-version = "2.0.12"
+version = "2.0.13"
 dependencies = [
  "serde_json",
 ]

package/crates/sks-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sks-core"
-version = "2.0.12"
+version = "2.0.13"
 edition = "2021"
 
 [dependencies]

package/crates/sks-core/src/main.rs

@@ -4,7 +4,7 @@ use std::io::{self, Read, Seek, SeekFrom};
 fn main() {
     let mut args = std::env::args().skip(1);
     match args.next().as_deref() {
-        Some("--version") => println!("sks-rs 2.0.12"),
+        Some("--version") => println!("sks-rs 2.0.13"),
         Some("compact-info") => {
             let mut input = String::new();
             let _ = io::stdin().read_to_string(&mut input);

package/dist/.sks-build-stamp.json

@@ -1,8 +1,8 @@
 {
   "schema": "sks.dist-build-stamp.v1",
   "package_name": "sneakoscope",
-  "package_version": "2.0.12",
-  "source_digest": "6f9f20ed184ebe714b41b9176d8414b7fded251a30591ada3c3bac53e49fcf61",
-  "source_file_count": 2053,
-  "built_at_source_time": 1780833723608
+  "package_version": "2.0.13",
+  "source_digest": "4e6d812c7572cee4b51a8e1d0374fff3b908c58e2173b6255122b87ce9e8b83e",
+  "source_file_count": 2090,
+  "built_at_source_time": 1780843454792
 }

package/dist/bin/sks.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const FAST_PACKAGE_VERSION = '2.0.12';
+const FAST_PACKAGE_VERSION = '2.0.13';
 const args = process.argv.slice(2);
 try {
     if (args[0] === '--agent' && args[1] === 'worker') {

package/dist/build-manifest.json

@@ -1,16 +1,16 @@
 {
   "schema": "sks.dist-build.v2",
-  "version": "2.0.12",
-  "package_version": "2.0.12",
+  "version": "2.0.13",
+  "package_version": "2.0.13",
   "typescript": true,
   "mjs_runtime_files": 0,
-  "compiled_file_count": 1111,
-  "compiled_js_count": 1111,
+  "compiled_file_count": 1127,
+  "compiled_js_count": 1127,
   "compiled_dts_count": 0,
-  "source_digest": "6f9f20ed184ebe714b41b9176d8414b7fded251a30591ada3c3bac53e49fcf61",
-  "source_file_count": 2053,
-  "source_files_hash": "cf94f337fb28d923dd91214e01c2b80794f0d24659e7aaac0baf5c3110f1eb7a",
-  "source_list_hash": "cf94f337fb28d923dd91214e01c2b80794f0d24659e7aaac0baf5c3110f1eb7a",
+  "source_digest": "4e6d812c7572cee4b51a8e1d0374fff3b908c58e2173b6255122b87ce9e8b83e",
+  "source_file_count": 2090,
+  "source_files_hash": "07ac9249be0189c641861e02515d575578156357d6a92cd33869ae8cc4a38691",
+  "source_list_hash": "07ac9249be0189c641861e02515d575578156357d6a92cd33869ae8cc4a38691",
   "src_mjs_runtime_files": 0,
   "dist_stamp_schema": "sks.dist-build-stamp.v1",
   "files": [
@@ -538,6 +538,21 @@
     "core/release/release-gate-scheduler.js",
     "core/reporting/markdown-table.js",
     "core/research.js",
+    "core/research/claim-evidence-matrix.js",
+    "core/research/experiment-plan.js",
+    "core/research/falsification.js",
+    "core/research/implementation-blueprint-markdown.js",
+    "core/research/implementation-blueprint.js",
+    "core/research/replication-pack.js",
+    "core/research/research-cycle-runner.js",
+    "core/research/research-final-reviewer.js",
+    "core/research/research-handoff.js",
+    "core/research/research-prompt-contract.js",
+    "core/research/research-quality-contract.js",
+    "core/research/research-report-quality.js",
+    "core/research/research-stage-runner.js",
+    "core/research/research-work-graph.js",
+    "core/research/source-quality-report.js",
     "core/responses-retry-policy.js",
     "core/retention.js",
     "core/router/capability-card.js",
@@ -1038,6 +1053,7 @@
     "scripts/repo-audit.js",
     "scripts/research-actual-route-backfill-check.js",
     "scripts/research-backfill-route-blackbox.js",
+    "scripts/research-quality-gate-check.js",
     "scripts/responses-retry-policy-centralized-check.js",
     "scripts/retention-cleanup-safety-check.js",
     "scripts/route-blackbox-realism-check.js",

package/dist/core/codex-control/codex-sdk-adapter.js

@@ -1,5 +1,8 @@
+import path from 'node:path';
+import { appendJsonl } from '../fsx.js';
 import { buildCodexSdkConfig } from './codex-sdk-config-policy.js';
 import { buildCodexSdkEnv } from './codex-sdk-env-policy.js';
+import { translateCodexSdkEvent } from './codex-event-translator.js';
 export async function runRealCodexSdkTask(input, policy) {
     const mod = await import('@openai/codex-sdk');
     const Codex = mod.Codex || mod.default?.Codex || mod.default;
@@ -22,9 +25,15 @@ export async function runRealCodexSdkTask(input, policy) {
     const thread = resumeId ? codex.resumeThread(resumeId, threadOptions) : codex.startThread(threadOptions);
     const events = [];
     let finalResponse = '';
+    let liveEventsWritten = false;
+    const liveEventPath = input.mutationLedgerRoot ? path.join(input.mutationLedgerRoot, 'codex-sdk-events.jsonl') : null;
     const streamed = await thread.runStreamed(buildSdkInput(input), { outputSchema: input.outputSchema });
     for await (const event of streamed.events) {
         events.push(event);
+        if (liveEventPath) {
+            await appendJsonl(liveEventPath, translateCodexSdkEvent(event));
+            liveEventsWritten = true;
+        }
         if (event?.type === 'item.completed' && event?.item?.type === 'agent_message')
             finalResponse = String(event.item.text || '');
     }
@@ -37,6 +46,7 @@ export async function runRealCodexSdkTask(input, policy) {
         finalResponse,
         structuredOutput,
         blockers: [],
+        liveEventsWritten,
         raw: { item_count: events.filter((event) => String(event?.type || '').startsWith('item.')).length }
     };
 }

package/dist/core/codex-control/codex-task-runner.js

@@ -67,8 +67,10 @@ export async function runCodexTask(input) {
     }
     const events = Array.isArray(adapterResult?.events) ? adapterResult.events : [];
     const translatedEvents = translateCodexSdkEvents(events);
-    for (const event of translatedEvents)
-        await appendJsonl(path.join(root, 'codex-sdk-events.jsonl'), event);
+    if (adapterResult?.liveEventsWritten !== true) {
+        for (const event of translatedEvents)
+            await appendJsonl(path.join(root, 'codex-sdk-events.jsonl'), event);
+    }
     if (adapterResult?.reliabilityShield)
         await writeJsonAtomic(path.join(root, 'codex-reliability-shield.json'), adapterResult.reliabilityShield);
     const structuredOutput = adapterResult?.structuredOutput;

package/dist/core/commands/research-command.js

@@ -14,6 +14,15 @@ import { scanDbSafety } from '../db-safety.js';
 import { maybeFinalizeRoute } from '../proof/auto-finalize.js';
 import { runNativeAgentOrchestrator } from '../agents/agent-orchestrator.js';
 import { flag, positionalArgs, readFlagValue, readMaxCycles, readBoundedIntegerFlag, resolveMissionId, safeReadTextFile } from './command-utils.js';
+import { writeResearchWorkGraph } from '../research/research-work-graph.js';
+import { runResearchCycle } from '../research/research-cycle-runner.js';
+import { readResearchQualityContract } from '../research/research-quality-contract.js';
+import { readClaimEvidenceMatrix } from '../research/claim-evidence-matrix.js';
+import { readSourceQualityReport } from '../research/source-quality-report.js';
+import { readImplementationBlueprint, validateImplementationBlueprint } from '../research/implementation-blueprint.js';
+import { readExperimentPlan, validateExperimentPlan } from '../research/experiment-plan.js';
+import { readReplicationPack, validateReplicationPack } from '../research/replication-pack.js';
+import { readResearchFinalReview } from '../research/research-final-reviewer.js';
 const RESEARCH_DEFAULT_MAX_CYCLES = 12;
 const RESEARCH_DEFAULT_CYCLE_TIMEOUT_MINUTES = 120;
 const RESEARCH_MIN_CYCLE_TIMEOUT_MINUTES = 15;
@@ -128,9 +137,12 @@ async function researchRun(args) {
     const dryRunPatches = flag(args, '--dry-run-patches') || flag(args, '--dryrun-patches');
     const maxWriteAgents = readBoundedIntegerFlag(args, '--max-write-agents', Math.min(requestedAgents, 5), 1, 20);
     const mock = flag(args, '--mock');
+    const researchWorkGraph = await writeResearchWorkGraph(dir, plan);
+    const graphWorkItemCount = Math.max(1, Number(researchWorkGraph.total_work_items || researchWorkGraph.work_items?.length || 0));
+    await runResearchCycle(dir, researchWorkGraph, { cycle: 0, status: mock ? 'mock_native_orchestrator_planned' : 'native_orchestrator_planned' });
     await setCurrent(root, { mission_id: id, mode: 'RESEARCH', phase: 'RESEARCH_RUNNING_NO_QUESTIONS', questions_allowed: false, implementation_allowed: false, research_real_run_required: !mock, research_cycle_timeout_minutes: cycleTimeoutMinutes });
     await appendJsonlBounded(path.join(dir, 'events.jsonl'), { ts: nowIso(), type: 'research.run.started', maxCycles, mock, cycleTimeoutMinutes, real_run_required: !mock });
-    const nativeAgentRun = await runNativeAgentOrchestrator({ root, missionId: id, route: flag(args, '--autoresearch') ? '$AutoResearch' : '$Research', prompt: mission.prompt || plan.prompt || 'Research run', backend: mock ? 'fake' : 'codex-sdk', mock, agents: requestedAgents, targetActiveSlots, desiredWorkItemCount, minimumWorkItems, maxQueueExpansion, concurrency: Math.min(requestedAgents, 5), readonly: !(applyPatches && writeMode !== 'off'), profile, writeMode: writeMode, applyPatches, dryRunPatches, maxWriteAgents, roster: plan.native_agent_plan, routeCommand: 'sks research run', routeBlackboxKind: 'actual_research_command' });
+    const nativeAgentRun = await runNativeAgentOrchestrator({ root, missionId: id, route: flag(args, '--autoresearch') ? '$AutoResearch' : '$Research', prompt: mission.prompt || plan.prompt || 'Research run', backend: mock ? 'fake' : 'codex-sdk', mock, agents: requestedAgents, targetActiveSlots, desiredWorkItemCount: Math.max(desiredWorkItemCount, graphWorkItemCount), minimumWorkItems: Math.max(minimumWorkItems, Math.min(graphWorkItemCount, targetActiveSlots)), maxQueueExpansion, concurrency: Math.min(requestedAgents, 5), readonly: true, profile, writeMode: writeMode, applyPatches: false, dryRunPatches, maxWriteAgents, roster: plan.native_agent_plan, routeCommand: 'sks research run', routeBlackboxKind: 'actual_research_command', narutoWorkGraph: researchWorkGraph });
     await writeJsonAtomic(path.join(dir, 'research-native-agent-run.json'), nativeAgentRun);
     await appendJsonlBounded(path.join(dir, 'events.jsonl'), { ts: nowIso(), type: 'research.native_agents.completed', backend: nativeAgentRun.backend, ok: nativeAgentRun.ok, proof: nativeAgentRun.proof?.status });
     if (mock) {
@@ -141,7 +153,7 @@ async function researchRun(args) {
         const proof = await maybeFinalizeRoute(root, { missionId: id, route: '$Research', gateFile: 'research-gate.json', gate: gate.gate || gate, artifacts: ['agents/agent-proof-evidence.json', 'research-native-agent-run.json', 'research-gate.json', 'research-report.md', researchPaperArtifactForPlan(plan), 'source-ledger.json', 'agent-ledger.json', 'debate-ledger.json', 'completion-proof.json'], mock, command: { cmd: `sks research run ${id} --mock`, status: 0 } });
         await setCurrent(root, { mission_id: id, mode: 'RESEARCH', phase: gate.passed ? 'RESEARCH_DONE' : 'RESEARCH_PAUSED', questions_allowed: true, implementation_allowed: false });
         if (flag(args, '--json'))
-            return console.log(JSON.stringify({ schema: flag(args, '--autoresearch') ? 'sks.autoresearch-run.v1' : 'sks.research-run.v1', ok: proof.ok, mission_id: id, gate, proof: proof.validation, native_agent_run: nativeAgentRun, agent_batches: plan.agent_batches, autoresearch_cycle_policy: plan.autoresearch_cycle_policy }, null, 2));
+            return console.log(JSON.stringify({ schema: flag(args, '--autoresearch') ? 'sks.autoresearch-run.v1' : 'sks.research-run.v1', ok: proof.ok, mission_id: id, gate, quality_metrics: gate.metrics || null, proof: proof.validation, native_agent_run: nativeAgentRun, research_work_graph: researchWorkGraph, agent_batches: plan.agent_batches, autoresearch_cycle_policy: plan.autoresearch_cycle_policy }, null, 2));
         console.log(`Mock research done: ${id}`);
         console.log(`Gate: ${gate.passed ? 'passed' : 'blocked'}`);
         return;
@@ -178,6 +190,7 @@ async function researchRun(args) {
         const cycleDir = path.join(dir, 'research', `cycle-${cycle}`);
         const outputFile = path.join(cycleDir, 'final.md');
         await appendJsonlBounded(path.join(dir, 'events.jsonl'), { ts: nowIso(), type: 'research.cycle.start', cycle, timeoutMinutes: cycleTimeoutMinutes, profile, enforced_reasoning_effort: 'xhigh' });
+        await runResearchCycle(dir, researchWorkGraph, { cycle, status: 'codex_research_cycle_started' });
         const prompt = buildResearchPrompt({ id, mission, plan, cycle, previous: last });
         const result = await runCodexExec({ root, prompt, outputFile, json: true, profile, extraArgs: researchCodexArgs, logDir: cycleDir, timeoutMs: cycleTimeoutMs });
         await writeJsonAtomic(path.join(cycleDir, 'process.json'), { code: result.code, stdout_tail: result.stdout, stderr_tail: result.stderr, stdout_bytes: result.stdoutBytes, stderr_bytes: result.stderrBytes, truncated: result.truncated, timed_out: result.timedOut });
@@ -212,7 +225,7 @@ async function researchRun(args) {
             await appendJsonlBounded(path.join(dir, 'events.jsonl'), { ts: nowIso(), type: 'research.done', cycle });
             await enforceRetention(root).catch(() => { });
             if (flag(args, '--json'))
-                return console.log(JSON.stringify({ schema: flag(args, '--autoresearch') ? 'sks.autoresearch-run.v1' : 'sks.research-run.v1', ok: proof.ok, mission_id: id, gate, proof: proof.validation, agent_batches: plan.agent_batches, autoresearch_cycle_policy: plan.autoresearch_cycle_policy }, null, 2));
+                return console.log(JSON.stringify({ schema: flag(args, '--autoresearch') ? 'sks.autoresearch-run.v1' : 'sks.research-run.v1', ok: proof.ok, mission_id: id, gate, quality_metrics: gate.metrics || null, proof: proof.validation, research_work_graph: researchWorkGraph, agent_batches: plan.agent_batches, autoresearch_cycle_policy: plan.autoresearch_cycle_policy }, null, 2));
             console.log(`Research done: ${id}`);
             return;
         }
@@ -246,6 +259,16 @@ async function researchStatus(args) {
     const agentRows = Array.isArray(agentLedger?.agents) ? agentLedger.agents : [];
     const sourceLayerRows = Array.isArray(sourceLedger?.source_layers) ? sourceLedger.source_layers : [];
     const sourceLayersCovered = sourceLayerRows.filter((layer) => layer.status === 'covered' && ((Array.isArray(layer.source_ids) && layer.source_ids.length) || (Array.isArray(layer.counterevidence_ids) && layer.counterevidence_ids.length))).length;
+    const qualityContract = await readResearchQualityContract(dir);
+    const claimMatrix = await readClaimEvidenceMatrix(dir);
+    const sourceQualityReport = await readSourceQualityReport(dir);
+    const implementationBlueprint = await readImplementationBlueprint(dir);
+    const experimentPlan = await readExperimentPlan(dir);
+    const replicationPack = await readReplicationPack(dir);
+    const finalReview = await readResearchFinalReview(dir);
+    const blueprintValidation = validateImplementationBlueprint(implementationBlueprint, qualityContract);
+    const experimentValidation = validateExperimentPlan(experimentPlan, qualityContract);
+    const replicationValidation = validateReplicationPack(replicationPack);
     console.log(JSON.stringify({
         mission,
         state,
@@ -275,7 +298,23 @@ async function researchStatus(args) {
         research_paper_artifact: paperArtifact.name,
         paper_present: Boolean(paperText.trim()),
         paper_sections: countResearchPaperSections(paperText),
-        falsification_cases: falsificationLedger?.cases?.length ?? null
+        falsification_cases: falsificationLedger?.cases?.length ?? null,
+        research_quality: {
+            contract: qualityContract,
+            report_word_count: gate?.metrics?.report_word_count ?? null,
+            claim_evidence_matrix_present: claimMatrix.present,
+            key_claims: claimMatrix.key_claim_ids.length,
+            triangulated_claims: claimMatrix.triangulated_claim_count,
+            claim_matrix_blockers: claimMatrix.blockers,
+            source_quality_report_ok: sourceQualityReport?.ok === true,
+            implementation_blueprint_sections: Array.isArray(implementationBlueprint?.sections) ? implementationBlueprint.sections.length : null,
+            implementation_blueprint_ok: blueprintValidation.ok,
+            experiment_steps: Array.isArray(experimentPlan?.steps) ? experimentPlan.steps.length : null,
+            experiment_plan_ok: experimentValidation.ok,
+            replication_pack_ok: replicationValidation.ok,
+            final_review_approved: finalReview?.approved === true,
+            final_review_blockers: finalReview?.blockers || []
+        }
     }, null, 2));
 }
 async function researchCodeMutationSnapshot(root, missionId = null) {

package/dist/core/fsx.js

@@ -5,7 +5,7 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-export const PACKAGE_VERSION = '2.0.12';
+export const PACKAGE_VERSION = '2.0.13';
 export const DEFAULT_PROCESS_TAIL_BYTES = 256 * 1024;
 export const DEFAULT_PROCESS_TIMEOUT_MS = 30 * 60 * 1000;
 export function nowIso() {

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