Add DeepMind-style progressive references and complete scientific runtime v4

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-science",
-  "version": "0.3.0+codex.20260720000100",
+  "version": "0.4.0+codex.20260721000100",
   "description": "Audited scientific skills, public-source tools, reproducible artifacts, and evidence review for Codex.",
   "author": {
     "name": "eightmm"

authored-skills/docking-validation/SKILL.md

@@ -6,6 +6,12 @@ license: MIT
 
 # Docking Validation
 
+## Reference usage
+
+Read [benchmark design](references/benchmark-design.md) before defining states, pockets, controls, or data splits. Read [metrics and acceptance](references/metric-and-acceptance.md) before computing metrics, fixing thresholds, calibrating scores, or declaring a pass. Read [inference boundaries](references/inference-boundaries.md) before writing pose, ranking, affinity, mechanism, or generalization claims.
+
+Do not infer benchmark information boundaries, metric aggregation, or claim strength from an engine name or score. Record the reference hashes used for a material benchmark or claim in a `reference-use-ledger`.
+
 ## Decision contract
 Prespecify the use case, prediction unit, receptor and ligand states, pocket information allowed at inference, benchmark split, controls, primary metric, uncertainty method, applicability domain, and success threshold before inspecting outcomes.
 Treat benchmark construction, preparation, pose generation, scoring, and decision analysis as separate stages with separate artifacts.

authored-skills/docking-validation/quality.json

@@ -0,0 +1,35 @@
+{
+  "schema_version": 1,
+  "skill": "docking-validation",
+  "roles": ["analyzer", "reviewer"],
+  "declared_maturity": "L4",
+  "output_schemas": [
+    "sbdd-benchmark-v1",
+    "numeric-metric-v1",
+    "pose-table-v1",
+    "model-receipt-v2",
+    "review-receipt-v2"
+  ],
+  "acceptance_fixtures": [
+    "examples/sbdd-acceptance/benchmark.json",
+    "examples/sbdd-acceptance/seeded-leaks.json",
+    "examples/sbdd-executable/input.json"
+  ],
+  "seeded_failures": [
+    "held-out-pocket-leak",
+    "analog-series-leak",
+    "scaffold-leak",
+    "cold-target-violation",
+    "known-training-overlap",
+    "missing-subgroup-analysis",
+    "affinity-overclaim"
+  ],
+  "test_files": [
+    "tests/test_sbdd_acceptance.py",
+    "tests/test_sbdd_execution.py"
+  ],
+  "limitations": [
+    "The deterministic executable fixture validates contract handling rather than prospective docking accuracy.",
+    "Docking scores and model confidence are not experimental affinity or mechanism."
+  ]
+}

authored-skills/docking-validation/references/benchmark-design.md

@@ -0,0 +1,31 @@
+# Docking benchmark design
+
+Read before creating a split, defining a pocket, choosing receptor states, or selecting positive and negative controls.
+
+## Prediction unit
+
+State whether the prediction unit is a complex, ligand, pose, target, target family, receptor state, or screening library. Metrics and independence groups must use the same unit.
+
+## State manifest
+
+Record biological assembly, chains, missing residues, mutations, protonation, tautomers, stereochemistry, formal charges, metals, cofactors, waters, covalent bonds, receptor state, ligand microstate, preparation software, parameters, and hashes.
+
+## Information boundary
+
+For a held-out complex, do not derive the pocket, ligand frame, receptor conformation, template, restraints, or feature engineering from the held-out bound pose unless the task explicitly permits that information.
+
+## Splits
+
+Preserve:
+
+- cold scaffold;
+- cold analog series;
+- cold target;
+- cold target family;
+- cold receptor state;
+- temporal holdout;
+- known and possible model-training overlap.
+
+## Controls
+
+At minimum include valid redocking controls, cross-docking where robustness is claimed, simple scoring or geometric baselines, chemically relevant negatives or property-matched decoys for screening, and known failure cases.

authored-skills/docking-validation/references/index.json

@@ -0,0 +1,40 @@
+{
+  "schema_version": 1,
+  "skill": "docking-validation",
+  "default_policy": "load-minimum-required",
+  "references": [
+    {
+      "id": "benchmark-design",
+      "path": "references/benchmark-design.md",
+      "purpose": "Define state manifests, information boundaries, leakage-aware splits, controls, and prediction units.",
+      "read_when": ["building a docking benchmark", "defining a pocket", "creating train/test splits"],
+      "required_before": ["benchmark-construction", "pocket-definition", "split-construction"],
+      "search_patterns": ["## Information boundary", "## Splits", "## Controls"],
+      "authority": "repository-contract",
+      "version": "1",
+      "evidence_boundary": "Defines benchmark validity; it does not show that a docking engine performs well."
+    },
+    {
+      "id": "metric-and-acceptance",
+      "path": "references/metric-and-acceptance.md",
+      "purpose": "Prespecify pose, screening, calibration, uncertainty, threshold, and failure metrics.",
+      "read_when": ["computing docking metrics", "setting acceptance thresholds", "calibrating scores"],
+      "required_before": ["metric-computation", "acceptance-decision", "score-calibration"],
+      "search_patterns": ["## Pose metrics", "## Screening metrics", "## Thresholds"],
+      "authority": "repository-contract",
+      "version": "1",
+      "evidence_boundary": "Metric definitions do not validate data splits, state preparation, or biological claims."
+    },
+    {
+      "id": "inference-boundaries",
+      "path": "references/inference-boundaries.md",
+      "purpose": "Keep pose, confidence, ranking, affinity, mechanism, and translational claims distinct.",
+      "read_when": ["writing docking conclusions", "claiming affinity or mechanism", "defining applicability or abstention"],
+      "required_before": ["docking-claim-synthesis", "affinity-claim", "mechanism-claim"],
+      "search_patterns": ["## Distinct outputs", "## Required external evidence", "## Claim downgrade"],
+      "authority": "repository-contract",
+      "version": "1",
+      "evidence_boundary": "Provides inference limits and does not supply assay or mechanistic evidence."
+    }
+  ]
+}

authored-skills/docking-validation/references/inference-boundaries.md

@@ -0,0 +1,30 @@
+# Docking inference boundaries
+
+Read before writing pose, ranking, affinity, selectivity, mechanism, or translational claims.
+
+## Distinct outputs
+
+Keep separate:
+
+- generated pose;
+- pose confidence;
+- docking or rescoring value;
+- ranking performance;
+- predicted affinity;
+- calibrated binding probability;
+- experimental affinity;
+- cellular or in vivo effect.
+
+A favorable docking score is not experimental affinity. A plausible pose is not a mechanism. A benchmark average is not evidence for one target–ligand pair outside the benchmark domain.
+
+## Required external evidence
+
+Affinity claims require assay-aware evidence with units, relation qualifiers, endpoint, conditions, and uncertainty. Mechanism claims require orthogonal structural, biochemical, mutational, kinetic, or cellular evidence as appropriate.
+
+## Applicability
+
+Report target family, receptor states, ligand classes, microstates, covalent or metal chemistry, size and flexibility range, and training-overlap state. Keep unsupported cases exploratory or abstain.
+
+## Claim downgrade
+
+When essential support is absent, downgrade from mechanistic to pose hypothesis, from affinity to ranking hypothesis, from generalization to within-benchmark performance, or from supported to inconclusive.

authored-skills/docking-validation/references/metric-and-acceptance.md

@@ -0,0 +1,23 @@
+# Docking metrics and acceptance
+
+Read before computing metrics, fixing thresholds, aggregating poses, or declaring a benchmark pass.
+
+## Pose metrics
+
+Report top-1 and top-k symmetry-aware heavy-atom RMSD, complete distributions, missing poses, and physical or chemical plausibility. Interaction recovery complements RMSD but does not replace geometry.
+
+## Screening metrics
+
+Use PR-AUC and prespecified enrichment metrics as primary measures when actives are rare. Report active/decoy counts, grouping, bootstrap intervals, and per-target results. ROC-AUC is secondary when class imbalance is material.
+
+## Calibration and abstention
+
+A score becomes a probability only after calibration on an appropriate held-out domain. Report reliability, Brier or log loss when relevant, subgroup calibration, and an abstention rule for unsupported chemical or target space.
+
+## Thresholds
+
+Fix metric, direction, threshold, confidence interval method, aggregation, exclusions, and subgroup requirements before inspecting held-out outcomes. Process completion is not an acceptance pass.
+
+## Failure taxonomy
+
+Distinguish preparation failure, unsupported chemistry, engine failure, no pose, invalid pose, geometric failure, interaction failure, ranking failure, calibration failure, and leakage invalidation.

authored-skills/literature-review/SKILL.md

@@ -8,6 +8,12 @@ license: MIT
 
 Use this conductor when the deliverable is an auditable body-of-evidence synthesis rather than a citation list or list of papers. Discovery tools retrieve records; this skill owns the protocol, eligibility, study identity, extraction, dependency graph, synthesis boundary, update diff, and review handoff.
 
+## Reference usage
+
+Before protocol freeze, study deduplication, or replication assessment, read [protocol and study identity](references/protocol-and-study-identity.md). Before structured extraction, risk-of-bias assessment, or claim-level evidence assertions, read [extraction and bias](references/extraction-and-bias.md). Before advancing a cutoff or replacing a reviewed snapshot, read [living update](references/living-update.md).
+
+Do not infer identifier relationships, extraction fields, bias judgments, or update invalidation rules from a record title. Save material reference use and SHA-256 values in a `reference-use-ledger`.
+
 ## Decision contract
 
 Before retrieval, record:

authored-skills/literature-review/quality.json

@@ -0,0 +1,35 @@
+{
+  "schema_version": 1,
+  "skill": "literature-review",
+  "roles": ["conductor", "analyzer"],
+  "declared_maturity": "L4",
+  "output_schemas": [
+    "literature-protocol-v1",
+    "query-ledger-v1",
+    "study-table-v1",
+    "study-family-v1",
+    "risk-of-bias-v1",
+    "claim-register-v1",
+    "evidence-graph-v2",
+    "literature-snapshot-v1-v2"
+  ],
+  "acceptance_fixtures": [
+    "examples/literature-review-reviewed-run/manifest.json",
+    "examples/literature-review-reviewed-run/snapshot.previous.json",
+    "examples/literature-review-reviewed-run/snapshot.current.json"
+  ],
+  "seeded_failures": [
+    "duplicate-study-identity",
+    "citation-mismatch",
+    "unsupported-conclusion",
+    "dependent-evidence-presented-as-replication"
+  ],
+  "test_files": [
+    "tests/test_evidence_sidecars.py",
+    "tests/test_collaboration_literature_v2.py"
+  ],
+  "limitations": [
+    "The checked-in reviewed run is a deterministic fixture rather than a live systematic-review conclusion.",
+    "Full-text licensing and source availability remain publication-specific."
+  ]
+}

authored-skills/literature-review/references/extraction-and-bias.md

@@ -0,0 +1,45 @@
+# Structured extraction and risk of bias
+
+Read before constructing the study table, effect extraction, risk-of-bias record, or claim-level evidence assertion.
+
+## Minimum study row
+
+Record, where applicable:
+
+- namespaced identifiers and study family;
+- publication state, funding, and conflicts;
+- design, setting, population or system, sample unit, sample size, and eligibility;
+- intervention or exposure, comparator, endpoint, follow-up, and attrition;
+- assay, preprocessing, model, covariates, missing-data handling, multiplicity correction, and protocol deviations;
+- effect measure, estimate, interval, unit, denominator, and exact source locator;
+- prespecified versus post-hoc status;
+- supported and contradicted claim IDs;
+- independence group and source dependencies.
+
+Do not infer missing methods, denominators, estimates, or uncertainty from an abstract or portal summary.
+
+## Risk-of-bias record
+
+Each record contains:
+
+```json
+{
+  "schema_version": 1,
+  "study_id": "study-1",
+  "instrument": "RoB 2 / ROBINS-I / domain-specific instrument",
+  "domains": [
+    {
+      "name": "selection",
+      "judgment": "low | some-concerns | high | unclear | not-applicable",
+      "rationale": "source-grounded reason"
+    }
+  ],
+  "overall_judgment": "..."
+}
+```
+
+A numeric summary score cannot replace domain judgments. The overall judgment cannot be more favorable than an essential high-risk domain without an explicit rationale.
+
+## Evidence assertion
+
+A material assertion should identify polarity, effect direction, effect measure, estimate and interval, population or system, exact source locator, independence group, and risk-of-bias reference. Citation presence alone is not sufficient.

authored-skills/literature-review/references/index.json

@@ -0,0 +1,40 @@
+{
+  "schema_version": 1,
+  "skill": "literature-review",
+  "default_policy": "load-minimum-required",
+  "references": [
+    {
+      "id": "protocol-and-study-identity",
+      "path": "references/protocol-and-study-identity.md",
+      "purpose": "Freeze the review protocol, normalize identifiers, resolve publication versions, and determine evidence independence.",
+      "read_when": ["freezing eligibility", "deduplicating studies", "resolving preprints, corrections, or registries"],
+      "required_before": ["protocol-freeze", "study-deduplication", "replication-assessment"],
+      "search_patterns": ["## Protocol freeze", "## Study-family resolution", "## Independence"],
+      "authority": "repository-contract",
+      "version": "1",
+      "evidence_boundary": "Defines review procedure; actual study records remain the evidence."
+    },
+    {
+      "id": "extraction-and-bias",
+      "path": "references/extraction-and-bias.md",
+      "purpose": "Construct study rows, effect assertions, source locators, and explicit risk-of-bias records.",
+      "read_when": ["extracting studies", "grading risk of bias", "writing claim-level evidence assertions"],
+      "required_before": ["structured-extraction", "risk-of-bias-assessment", "evidence-assertion"],
+      "search_patterns": ["## Minimum study row", "## Risk-of-bias record", "## Evidence assertion"],
+      "authority": "repository-contract",
+      "version": "1",
+      "evidence_boundary": "Does not supply missing study values or replace primary-source verification."
+    },
+    {
+      "id": "living-update",
+      "path": "references/living-update.md",
+      "purpose": "Advance a literature snapshot without overwriting prior evidence or reusing stale review receipts.",
+      "read_when": ["running living-update mode", "changing an evidence cutoff", "replacing a reviewed synthesis"],
+      "required_before": ["living-review-update", "review-snapshot-replacement"],
+      "search_patterns": ["## Immutable snapshots", "## Update diff", "## Invalidation"],
+      "authority": "repository-contract",
+      "version": "1",
+      "evidence_boundary": "Controls update lineage; it does not establish that new evidence changes a claim."
+    }
+  ]
+}

authored-skills/literature-review/references/living-update.md

@@ -0,0 +1,33 @@
+# Living review updates
+
+Read before advancing an evidence cutoff, replacing a reviewed synthesis, or reusing a prior review receipt.
+
+## Immutable snapshots
+
+Preserve the prior protocol, exact queries, source releases, included and excluded studies, study-family mapping, claim register, and reviewed report. Create a new snapshot rather than editing the old one.
+
+## Update diff
+
+Compare:
+
+- query additions, removals, and changes;
+- source availability or release changes;
+- added, removed, and modified studies;
+- publication-version, correction, and retraction changes;
+- eligibility decisions;
+- risk-of-bias changes;
+- claim status, confidence, and applicability changes.
+
+Use:
+
+```bash
+python scripts/diff_literature_review.py previous.json current.json --output diff.json
+```
+
+## Invalidation
+
+Invalidate the previous review receipt when covered queries, source snapshots, study table, evidence graph, extraction, claim register, or report bytes change. A narrative that appears unchanged still requires re-review when its evidence dependencies changed.
+
+## Stop rule
+
+Stop the update when every source has reached the declared cutoff, pagination is complete or explicitly bounded, unresolved study identities are visible, and claim-level changes have been reviewed. Source failure is unavailable evidence, not a negative study.