pen-stack 4.5.1__tar.gz → 5.1.0__tar.gz

{pen_stack-4.5.1 → pen_stack-5.1.0}/CHANGELOG.md

@@ -3,6 +3,63 @@
 All notable changes to PEN-STACK are documented here. This file follows
 [Keep a Changelog](https://keepachangelog.com/) and the program's phase structure.
 
+## [5.1.0] - 2026-06-10 - v5.1 release: Delivery immunology (the safety↔efficacy balance)
+
+The delivery palette gains a **documented, cited, qualitative immune + safety + efficacy profile** per vehicle,
+so the substrate can make the safety↔efficacy tradeoff legible and user-weightable — without ever predicting an
+immune magnitude (that stays a declared known-unknown). Workstream WS-IMMUNE, SHA-locked.
+
+### Added
+- **WS-IMMUNE config** — `configs/delivery_vehicles.yaml` (v1.1): an `immune_safety` block on all 8 vehicles
+  (`preexisting_immunity`, `neutralizing_antibody`, `innate_immune`, `adaptive_immune`, `genotoxicity`,
+  `efficacy`, `tradeoff`, `immune_dois`) — DOCUMENTED ordinal low/moderate/high priors, every `immune_doi`
+  Crossref-verified and in the curated-DOI set (citations resolve by construction).
+- **WS-IMMUNE planner** — `pen_stack/planner/delivery_immunology.py`: `safety_efficacy_profile()` reports two
+  **separate** safety sub-axes — `immune_score` (immunogenicity; reversible, eligibility/re-dosing) and
+  `genotox_score` (insertional/oncogenic; permanent) — never collapsed, with headline
+  `safety_score = min(immune_score, genotox_score)` (precautionary worst-axis). `recommend_delivery(cargo_form,
+  cargo_bp, safety_weight, in_vivo)` ranks the eligible palette along the safety↔efficacy frontier by a
+  user-supplied weight. Reproduces the stated tradeoff: AAV is dinged on immunogenicity, lentivirus on
+  genotoxicity. `prereg/ws_immune.yaml`.
+- **WS-IMMUNE verify** — `Verdict.delivery_profile` + a `delivery_immune_profile` scope flag: `verify()` now
+  surfaces the documented profile and tradeoff for a chosen vehicle, always attaching the standing
+  `in_vivo_immunogenicity` known-unknown flag — never adding confidence, never predicting a magnitude.
+
+### Changed
+- Version 5.0.0 -> 5.1.0 (minor — additive delivery-immunology layer); `cite.curated_dois()` now also ingests
+  the per-vehicle `immune_dois`.
+
+### Honesty invariant (unchanged)
+- The in-vivo immune MAGNITUDE (patient/construct-specific response) remains a declared known-unknown
+  (`configs/known_unknowns.yaml: in_vivo_immunogenicity`) and is **never** predicted. v5.1 exposes only
+  documented ordinal priors plus a transparent, user-weighted ranking — it makes the boundary legible, it does
+  not close it.
+
+## [5.0.0] - 2026-06-09 - v5.0 release: the Co-Scientist (capstone — smart because it is grounded)
+
+The reasoning ceiling rises while the grounding floor stays fixed: a co-scientist that proposes multiple
+distinct strategies, critiques and revises its own plans, cites its reasoning, and itemises what it cannot
+assess — with **no-fabrication holding across the full reasoning stack** (the central gate). Workstreams
+WS-{PLAN,MULTI,CRIT,SCOPE2,CITE,GEN}, each SHA-locked.
+
+### Added
+- **WS-PLAN + WS-MULTI** — `pen_stack/agent/co_scientist.py`: `propose_strategies()` returns 2–3 **materially
+  distinct** strategies (≥2 design axes differ — measured by `distinctness()`, not reworded), each
+  independently legal + confidence-tagged; `deliberate()` benchmarks the deliberative planner vs the
+  deterministic baseline. `prereg/ws_plan.yaml`.
+- **WS-CRIT + WS-SCOPE2** — `critique()` / `critique_and_revise()` (the critic only flags + swaps a design
+  choice, never invents a number; revisions re-verified) + `critique_falsifiability()` (improves flawed plans
+  illegal→legal, 0 spurious revisions on clean) + `scope_ledger()` (per-recommendation: what was/ wasn't
+  assessed, the known-unknowns itemised). `prereg/ws_crit.yaml`.
+- **WS-CITE + WS-GEN** — `pen_stack/agent/cite.py`: `cited_rationale()` (citations drawn from the curated
+  world-model → resolve by construction) + `citations_grounded()` guard (rejects any DOI not in the curated
+  set) + `generalise()` (adjacent tasks grounded-or-refused). `prereg/ws_cite.yaml`.
+- **Bench v0.3.2** — `co_scientist_grounded` reference-solver task: grounded rate 1.0 vs ungrounded 0.0;
+  no-fabrication across the full stack. `docs/co_scientist.md`.
+
+### Changed
+- Version 4.5.1 -> 5.0.0 (major — the substrate matured into a grounded co-scientist); bench 0.3.1 -> 0.3.2.
+
 ## [4.5.1] - 2026-06-09 - ID-correctness patch: cell-type ontology IDs
 
 ### Fixed

{pen_stack-4.5.1 → pen_stack-5.1.0}/CITATION.cff

@@ -1,8 +1,8 @@
 cff-version: 1.2.0
 message: "If you use PEN-STACK, please cite it as below."
 title: "PEN-STACK: open infrastructure for genome writing"
-version: 4.5.1
-date-released: 2026-06-01
+version: 5.1.0
+date-released: 2026-06-10
 authors:
   - family-names: "Mahaboob Ali"
     given-names: "Anees Ahmed"

{pen_stack-4.5.1 → pen_stack-5.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 4.5.1
+Version: 5.1.0
 Summary: Open infrastructure for genome writing: the Writable Genome atlas, the Writer Atlas, and the Write Planner.
 Author-email: Anees Ahmed Mahaboob Ali <ahmedaneesm@gmail.com>
 License: MIT
@@ -77,10 +77,12 @@ Dynamic: license-file
 
 # PEN-STACK
 
-### The Writable Genome - open infrastructure for genome *writing*
+### The verification & grounding substrate for genome-writing AI — matured into a co-scientist
 
-*Editing tools tell you **how** to change a base. PEN-STACK tells you **where** in the genome you can safely
-and durably write new DNA, **which enzyme** can write it there, and **how** to design the write end-to-end.*
+*The foundation models *generate*; PEN-STACK *checks*. It tells you **where** in the genome you can safely and
+durably write, **which enzyme** can write it there, and **how** to design the write end-to-end — then verifies
+every design against rule-grounded mechanism, reports calibrated confidence, cites its reasoning, and says
+"out of scope" rather than guess. Every number comes from a validated tool; nothing is fabricated.*
 
 [![PyPI](https://img.shields.io/pypi/v/pen-stack.svg)](https://pypi.org/project/pen-stack/)
 [![CI](https://github.com/ahmedanees-m/pen-stack/actions/workflows/ci.yml/badge.svg)](https://github.com/ahmedanees-m/pen-stack/actions/workflows/ci.yml)
@@ -89,12 +91,12 @@ and durably write new DNA, **which enzyme** can write it there, and **how** to d
 [![codecov](https://codecov.io/gh/ahmedanees-m/pen-stack/branch/main/graph/badge.svg)](https://codecov.io/gh/ahmedanees-m/pen-stack)
 [![License: MIT](https://img.shields.io/badge/License-MIT-informational.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
-[![Version](https://img.shields.io/badge/version-4.5.1-blue.svg)](CHANGELOG.md)
-[![Tests](https://img.shields.io/badge/tests-224%20passing-success.svg)](tests/)
+[![Version](https://img.shields.io/badge/version-5.1.0-blue.svg)](CHANGELOG.md)
+[![Tests](https://img.shields.io/badge/tests-240%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)
 [![Runtime: Docker](https://img.shields.io/badge/runtime-docker-2496ED.svg)](docker/)
 [![Validation: pre-registered](https://img.shields.io/badge/validation-pre--registered-critical.svg)](prereg/)
-[![Genome-Writing Bench v0.3](https://img.shields.io/badge/benchmark-Genome--Writing%20Bench%20v0.3.1-6f42c1.svg)](benchmarks/genome_writing_bench/)
+[![Genome-Writing Bench v0.3](https://img.shields.io/badge/benchmark-Genome--Writing%20Bench%20v0.3.2-6f42c1.svg)](benchmarks/genome_writing_bench/)
 
 **Built on five prior, separately published repositories:**
 
@@ -133,6 +135,40 @@ Two questions gate every genome-writing project, and before PEN-STACK no resourc
 Everything is built on bulk-downloadable public data, runs on a single GPU, and is validated **blind** against
 a pre-registered, honest baseline before release.
 
+## What is new in v5.1 — Delivery immunology (the safety↔efficacy balance)
+
+v5.1 makes the delivery palette's **safety↔efficacy tradeoff legible and user-weightable**. Every vehicle now
+carries a documented, cited, qualitative immune + safety + efficacy profile — so you can ask for a *balance*
+(AAV is safe by integration but neutralizing-antibody/pre-existing-immunity limited; lentivirus is a highly
+efficacious integrator but its genotoxicity is the dominant concern). Crucially, the in-vivo immune
+**magnitude** stays a declared known-unknown — v5.1 surfaces documented priors, it does **not** predict a
+patient-specific immune response.
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **IMMUNE config** | `immune_safety` block on all 8 vehicles in `configs/delivery_vehicles.yaml` | documented ordinal (low/moderate/high) priors for pre-existing immunity, neutralizing antibody, innate/adaptive immune, **genotoxicity**, efficacy — every `immune_doi` Crossref-verified and in the curated-DOI set |
+| **IMMUNE planner** | `planner/delivery_immunology.py` — `safety_efficacy_profile()` / `recommend_delivery()` | two **separate** safety sub-axes (`immune_score` reversible vs `genotox_score` permanent), never collapsed; headline `safety_score = min(...)` (worst-axis); ranks the palette along the safety↔efficacy frontier by a **user weight** |
+| **IMMUNE verify** | `Verdict.delivery_profile` + `delivery_immune_profile` scope flag | `verify()` surfaces the documented tradeoff for a chosen vehicle, always attaching the `in_vivo_immunogenicity` known-unknown flag — never adding confidence, never predicting a magnitude |
+
+See `prereg/ws_immune.yaml`.
+
+## What is new in v5.0 — the Co-Scientist (smart because it is grounded)
+
+v5.0 matures the reasoning layer on top of everything beneath it. Given a goal and an intent, PEN-STACK
+returns a small set of **materially distinct, ranked, fully-traceable strategies** — each verified,
+calibrated, cited, and scope-ledgered — while the **no-fabrication guarantee holds by construction**: the
+reasoning layer proposes and critiques, but every number still comes from a validated tool or oracle.
+Intelligence rises while groundedness never falls.
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **PLAN + MULTI** | `agent/co_scientist.py` — `propose_strategies()` / `deliberate()` | 2–3 **materially-distinct** strategies (≥2 design axes differ — *measured*, not reworded), each independently **legal** + **confidence-tagged**; deliberative planner benchmarked vs the deterministic baseline |
+| **CRIT + SCOPE2** | self-critique/revise loop + scope ledger | the critic only flags + swaps (never invents a number); revisions are **re-verified** and **falsifiable** (improve flawed plans illegal→legal, never touch clean ones); every recommendation carries a **complete scope ledger** itemising the known-unknowns |
+| **CITE + GEN** | `agent/cite.py` — cited rationale + scoped generalisation | citations are **drawn from the curated world-model** (resolve by construction); a guard **rejects any hallucinated DOI**; adjacent tasks are **grounded-or-refused** |
+| **central gate** | `co_scientist_grounded` bench (v0.3.2) | grounded rate **1.0** vs ungrounded **0.0**; **no-fabrication holds across the full reasoning stack** (asserted) |
+
+See `docs/co_scientist.md` and `prereg/ws_{plan,crit,cite}.yaml`.
+
 ## What is new in v4.5 — the Living World-Model (a knowledge graph that keeps itself current)
 
 v4.5 promotes the flat atlas/WT-KB/crosslink tables into a queryable **knowledge graph**: writers, loci,
@@ -412,7 +448,7 @@ pen-stack/
 │   │                                   + v3.3 router (write-type dispatch) / delivery_vehicles (8-vehicle palette)
 │   ├── bridge/                       bridge off-target engine (Paper 4): offtarget / fold_qc / guide_qc / pipeline / cli
 │   │                                   + v3.2 offtarget_energetics (position x substitution; held-out 0.88, ships)
-│   ├── agent/                        agentic platform: tools / orchestrator / pen_agent / mcp_server / guardrails
+│   ├── agent/                        agentic platform: tools / orchestrator / pen_agent / mcp_server / guardrails; v5.0 co_scientist + cite (multi-strategy, self-critique, cited rationale, scope ledger)
 │   │                                   + v3.2 epistemic (3-tier status) / scope (known-unknowns matcher)
 │   ├── graph/                        v4.5 living world-model knowledge graph (schema/build/query/ingest/cell_types); typed provenanced edges; gated living loop (propose-only)
 │   ├── oracles/                      v4.0 L1 oracle mesh: OracleResult contract + adapters (genome/structure/protein_design/rna/energetics) over the foundation models; version-pinned cache

{pen_stack-4.5.1 → pen_stack-5.1.0}/README.md

@@ -2,10 +2,12 @@
 
 # PEN-STACK
 
-### The Writable Genome - open infrastructure for genome *writing*
+### The verification & grounding substrate for genome-writing AI — matured into a co-scientist
 
-*Editing tools tell you **how** to change a base. PEN-STACK tells you **where** in the genome you can safely
-and durably write new DNA, **which enzyme** can write it there, and **how** to design the write end-to-end.*
+*The foundation models *generate*; PEN-STACK *checks*. It tells you **where** in the genome you can safely and
+durably write, **which enzyme** can write it there, and **how** to design the write end-to-end — then verifies
+every design against rule-grounded mechanism, reports calibrated confidence, cites its reasoning, and says
+"out of scope" rather than guess. Every number comes from a validated tool; nothing is fabricated.*
 
 [![PyPI](https://img.shields.io/pypi/v/pen-stack.svg)](https://pypi.org/project/pen-stack/)
 [![CI](https://github.com/ahmedanees-m/pen-stack/actions/workflows/ci.yml/badge.svg)](https://github.com/ahmedanees-m/pen-stack/actions/workflows/ci.yml)
@@ -14,12 +16,12 @@ and durably write new DNA, **which enzyme** can write it there, and **how** to d
 [![codecov](https://codecov.io/gh/ahmedanees-m/pen-stack/branch/main/graph/badge.svg)](https://codecov.io/gh/ahmedanees-m/pen-stack)
 [![License: MIT](https://img.shields.io/badge/License-MIT-informational.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
-[![Version](https://img.shields.io/badge/version-4.5.1-blue.svg)](CHANGELOG.md)
-[![Tests](https://img.shields.io/badge/tests-224%20passing-success.svg)](tests/)
+[![Version](https://img.shields.io/badge/version-5.1.0-blue.svg)](CHANGELOG.md)
+[![Tests](https://img.shields.io/badge/tests-240%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)
 [![Runtime: Docker](https://img.shields.io/badge/runtime-docker-2496ED.svg)](docker/)
 [![Validation: pre-registered](https://img.shields.io/badge/validation-pre--registered-critical.svg)](prereg/)
-[![Genome-Writing Bench v0.3](https://img.shields.io/badge/benchmark-Genome--Writing%20Bench%20v0.3.1-6f42c1.svg)](benchmarks/genome_writing_bench/)
+[![Genome-Writing Bench v0.3](https://img.shields.io/badge/benchmark-Genome--Writing%20Bench%20v0.3.2-6f42c1.svg)](benchmarks/genome_writing_bench/)
 
 **Built on five prior, separately published repositories:**
 
@@ -58,6 +60,40 @@ Two questions gate every genome-writing project, and before PEN-STACK no resourc
 Everything is built on bulk-downloadable public data, runs on a single GPU, and is validated **blind** against
 a pre-registered, honest baseline before release.
 
+## What is new in v5.1 — Delivery immunology (the safety↔efficacy balance)
+
+v5.1 makes the delivery palette's **safety↔efficacy tradeoff legible and user-weightable**. Every vehicle now
+carries a documented, cited, qualitative immune + safety + efficacy profile — so you can ask for a *balance*
+(AAV is safe by integration but neutralizing-antibody/pre-existing-immunity limited; lentivirus is a highly
+efficacious integrator but its genotoxicity is the dominant concern). Crucially, the in-vivo immune
+**magnitude** stays a declared known-unknown — v5.1 surfaces documented priors, it does **not** predict a
+patient-specific immune response.
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **IMMUNE config** | `immune_safety` block on all 8 vehicles in `configs/delivery_vehicles.yaml` | documented ordinal (low/moderate/high) priors for pre-existing immunity, neutralizing antibody, innate/adaptive immune, **genotoxicity**, efficacy — every `immune_doi` Crossref-verified and in the curated-DOI set |
+| **IMMUNE planner** | `planner/delivery_immunology.py` — `safety_efficacy_profile()` / `recommend_delivery()` | two **separate** safety sub-axes (`immune_score` reversible vs `genotox_score` permanent), never collapsed; headline `safety_score = min(...)` (worst-axis); ranks the palette along the safety↔efficacy frontier by a **user weight** |
+| **IMMUNE verify** | `Verdict.delivery_profile` + `delivery_immune_profile` scope flag | `verify()` surfaces the documented tradeoff for a chosen vehicle, always attaching the `in_vivo_immunogenicity` known-unknown flag — never adding confidence, never predicting a magnitude |
+
+See `prereg/ws_immune.yaml`.
+
+## What is new in v5.0 — the Co-Scientist (smart because it is grounded)
+
+v5.0 matures the reasoning layer on top of everything beneath it. Given a goal and an intent, PEN-STACK
+returns a small set of **materially distinct, ranked, fully-traceable strategies** — each verified,
+calibrated, cited, and scope-ledgered — while the **no-fabrication guarantee holds by construction**: the
+reasoning layer proposes and critiques, but every number still comes from a validated tool or oracle.
+Intelligence rises while groundedness never falls.
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **PLAN + MULTI** | `agent/co_scientist.py` — `propose_strategies()` / `deliberate()` | 2–3 **materially-distinct** strategies (≥2 design axes differ — *measured*, not reworded), each independently **legal** + **confidence-tagged**; deliberative planner benchmarked vs the deterministic baseline |
+| **CRIT + SCOPE2** | self-critique/revise loop + scope ledger | the critic only flags + swaps (never invents a number); revisions are **re-verified** and **falsifiable** (improve flawed plans illegal→legal, never touch clean ones); every recommendation carries a **complete scope ledger** itemising the known-unknowns |
+| **CITE + GEN** | `agent/cite.py` — cited rationale + scoped generalisation | citations are **drawn from the curated world-model** (resolve by construction); a guard **rejects any hallucinated DOI**; adjacent tasks are **grounded-or-refused** |
+| **central gate** | `co_scientist_grounded` bench (v0.3.2) | grounded rate **1.0** vs ungrounded **0.0**; **no-fabrication holds across the full reasoning stack** (asserted) |
+
+See `docs/co_scientist.md` and `prereg/ws_{plan,crit,cite}.yaml`.
+
 ## What is new in v4.5 — the Living World-Model (a knowledge graph that keeps itself current)
 
 v4.5 promotes the flat atlas/WT-KB/crosslink tables into a queryable **knowledge graph**: writers, loci,
@@ -337,7 +373,7 @@ pen-stack/
 │   │                                   + v3.3 router (write-type dispatch) / delivery_vehicles (8-vehicle palette)
 │   ├── bridge/                       bridge off-target engine (Paper 4): offtarget / fold_qc / guide_qc / pipeline / cli
 │   │                                   + v3.2 offtarget_energetics (position x substitution; held-out 0.88, ships)
-│   ├── agent/                        agentic platform: tools / orchestrator / pen_agent / mcp_server / guardrails
+│   ├── agent/                        agentic platform: tools / orchestrator / pen_agent / mcp_server / guardrails; v5.0 co_scientist + cite (multi-strategy, self-critique, cited rationale, scope ledger)
 │   │                                   + v3.2 epistemic (3-tier status) / scope (known-unknowns matcher)
 │   ├── graph/                        v4.5 living world-model knowledge graph (schema/build/query/ingest/cell_types); typed provenanced edges; gated living loop (propose-only)
 │   ├── oracles/                      v4.0 L1 oracle mesh: OracleResult contract + adapters (genome/structure/protein_design/rna/energetics) over the foundation models; version-pinned cache

{pen_stack-4.5.1 → pen_stack-5.1.0}/benchmarks/genome_writing_bench/LEADERBOARD.md

@@ -1,12 +1,12 @@
-# Genome-Writing Bench v0.3.1 - Leaderboard
+# Genome-Writing Bench v0.3.2 - Leaderboard
 
-Tasks: **15/15 available** in this run (unavailable = needs the Phase-1 atlas / Perry tables / an LLM, which run on the VM/local).
-Deterministic planner beats the naive baseline on **11/11** grounded tasks with a baseline.
+Tasks: **16/16 available** in this run (unavailable = needs the Phase-1 atlas / Perry tables / an LLM, which run on the VM/local).
+Deterministic planner beats the naive baseline on **12/12** grounded tasks with a baseline.
 
 | Solver | Tasks scored | Beats naive | No-fabrication | Note |
 |---|---|---|---|---|
-| deterministic_planner | 15 | 11/11 | n/a (deterministic) | validated planning tools - the reference |
-| naive_baseline | 11 | - | n/a (deterministic) | safety-only / prevalence / Hamming baselines |
+| deterministic_planner | 16 | 12/12 | n/a (deterministic) | validated planning tools - the reference |
+| naive_baseline | 12 | - | n/a (deterministic) | safety-only / prevalence / Hamming baselines |
 
 ## Per-task results
 | Task | Family | Available | Planner | Naive baseline | Gate |
@@ -26,6 +26,7 @@ Deterministic planner beats the naive baseline on **11/11** grounded tasks with
 | multi_write_type_legality | MW_multi_write_type | True | 1.0 | 0.0 | - |
 | adversarial_robustness | T13_scope_disguise | True | 1.0 | 0.0 | - |
 | graph_multihop_reasoning | GR_graph_reasoning | True | 1.0 | 0.0 | - |
+| co_scientist_grounded | CS_co_scientist | True | 1.0 | 0.0 | - |
 
 ## Trust tasks (T8-T11) - calibration + scope-awareness separate *trustworthy* agents
 Each contrasts the **uncertainty-aware** agent (conformal coverage, selective prediction, OOD flagging, out-of-scope deferral) with an **over-confident** baseline (an uncalibrated interval, no abstention, never flags OOD, no scope layer). The over-confident agent is the realistic failure mode a calibrated co-scientist must beat.

{pen_stack-4.5.1 → pen_stack-5.1.0}/benchmarks/genome_writing_bench/tasks.yaml

@@ -8,7 +8,7 @@
 # A task names a `scorer` (module.function in pen_stack.validate / pen_stack.bridge) and a `metric` key to
 # read from its report. Solvers (deterministic planner, naive baseline, LLM agent) are compared on the same
 # tasks; a solver that cannot ground a number must refuse, not invent (no-fabrication is a hard gate).
-version: "0.3.1"
+version: "0.3.2"
 prepared: "2026-06-09"
 
 taxonomy:
@@ -35,6 +35,8 @@ taxonomy:
   T16_distribution_shift: "an OOD context -> confidence is deflated (extrapolating), not reported at the in-distribution level"
   # v0.3.1 (v4.5): multi-hop reasoning over the living world-model graph.
   GR_graph_reasoning:   "answer a multi-hop design question (writers reaching a locus AND deliverable carrying a cargo form) as a PROVENANCED graph traversal (vs an ungrounded agent that cannot cite a path)"
+  # v0.3.2 (v5.0): the matured co-scientist as reference solver.
+  CS_co_scientist:      "end-to-end grounded design: multiple materially-distinct legal confidence-tagged strategies, each citation-grounded + scope-ledgered, no-fabrication across the full reasoning stack (vs an ungrounded agent producing none of these)"
 
 tasks:
   - id: site_selection_blind_gsh
@@ -207,3 +209,18 @@ tasks:
     circular: false
     note: "v4.5 world-model graph: a design question answered as one grounded traversal; an ungrounded agent
       has no graph and cannot produce a provenanced path (0 by construction). no-fabrication holds."
+
+  # ---- v0.3.2 (v5.0): the matured co-scientist as the reference solver.
+  - id: co_scientist_grounded
+    family: CS_co_scientist
+    scorer: "pen_stack.validate.bench_coscientist_tasks:run"
+    metric: "co_scientist_grounded_rate"
+    baseline_metric: "ungrounded_baseline_rate"
+    higher_is_better: true
+    ground_truth: "frozen panel of write goals; a recommendation set is 'fully grounded' iff it is multiple
+      materially-distinct (>=2 design axes) + each legal (verifier) + confidence-tagged (calibrated) + the
+      rationale's citations are in the curated DOI set + the scope ledger is complete + no-fabrication - all
+      mechanistic/verifier facts, not the agent's own claim (non-circular)"
+    circular: false
+    note: "v5.0 capstone: the matured co-scientist; the central gate is no-fabrication under the FULL reasoning
+      stack. An ungrounded agent produces none of these grounded properties (0 by construction)."

pen_stack-5.1.0/configs/delivery_vehicles.yaml

@@ -0,0 +1,185 @@
+# PEN-STACK v3.3 — Delivery vehicle palette (WS-D / North-Star §4). The substrate must score and constrain
+# the WHOLE delivery palette, not just dual-AAV. Each row: cargo capacity, integration, division dependence,
+# immunogenicity PRIOR (qualitative; MAGNITUDE is a known-unknown — never predicted), re-dosability, tropism,
+# ex/in-vivo, compatible cargo form {DNA, mRNA, RNP}, and >=1 DOI. Values cited to 2026 sources.
+# `constraint_key` maps to configs/delivery_constraints.yaml for the sequence-level scan.
+#
+# v5.1 — `immune_safety`: a DOCUMENTED, CITED, QUALITATIVE (low/moderate/high) immune + safety + efficacy
+# profile per vehicle, for the safety<->efficacy balance (planner/delivery_immunology.py). These are ordinal
+# DOCUMENTED PRIORS from the literature — NOT a predicted, patient- or construct-specific immune magnitude
+# (that stays a known-unknown / scope flag, `in_vivo_immunogenicity`, never predicted). `genotoxicity` = the
+# integration / insertional-mutagenesis risk; `efficacy` = transduction/integration efficiency.
+
+version: "1.1"
+
+vehicles:
+  AAV_single:
+    cargo_capacity_bp: 4700
+    integrating: false            # episomal
+    division_dependent: false
+    immunogenicity_prior: "moderate-high; pre-existing NAbs exclude 30-60% of patients"
+    re_dosable: false
+    tropism: "serotype-dependent (liver, muscle, CNS, retina)"
+    in_vivo: true
+    compatible_cargo_form: [DNA]
+    constraint_key: AAV
+    dois: ["10.1038/s41573-019-0012-9"]
+    immune_safety:
+      preexisting_immunity: high       # serotype-dependent; seroprevalence ~30-60% of patients
+      neutralizing_antibody: high      # pre-existing + vector-elicited NAbs; exclude/relapse risk
+      innate_immune: low
+      adaptive_immune: moderate        # capsid-directed CD8 T-cell responses
+      genotoxicity: low                # episomal, non-integrating
+      efficacy: high                   # efficient in-vivo transduction (cargo-limited ~4.7 kb)
+      tradeoff: "safe vector (non-integrating, low genotoxicity) BUT pre-existing/elicited NAbs limit eligibility and prevent re-dosing"
+      immune_dois: ["10.1182/blood-2013-01-306647", "10.1089/hum.2009.182", "10.1016/j.ymthe.2019.12.010"]
+
+  AAV_dual:
+    cargo_capacity_bp: 9000       # split across 2 capsids (~9 kb); efficiency drops sharply
+    integrating: false
+    division_dependent: false
+    immunogenicity_prior: "as AAV; split lowers efficiency"
+    re_dosable: false
+    tropism: "serotype-dependent"
+    in_vivo: true
+    compatible_cargo_form: [DNA]
+    constraint_key: AAV
+    dois: ["10.1128/JVI.79.15.9933-9944.2005"]   # Grieger & Samulski 2005, AAV packaging capacity
+    immune_safety:
+      preexisting_immunity: high       # same AAV capsid immunology as single
+      neutralizing_antibody: high
+      innate_immune: low
+      adaptive_immune: moderate
+      genotoxicity: low                # episomal
+      efficacy: moderate               # split across 2 capsids -> co-transduction needed, efficiency drops
+      tradeoff: "as AAV (non-integrating, NAb-limited) AND split-capsid co-transduction lowers efficiency"
+      immune_dois: ["10.1182/blood-2013-01-306647", "10.1089/hum.2009.182"]
+
+  lentivirus:
+    cargo_capacity_bp: 8000
+    integrating: true             # semi-random integration
+    division_dependent: false     # integrates in non-dividing too; strong in dividing
+    immunogenicity_prior: "moderate"
+    re_dosable: false
+    tropism: "broad (VSV-G pseudotyped)"
+    ex_vivo: true
+    compatible_cargo_form: [DNA]
+    constraint_key: lentiviral
+    dois: ["10.1126/science.1233151"]
+    immune_safety:
+      preexisting_immunity: low        # pseudotyped, typically ex-vivo (no host pre-immunity to the vector)
+      neutralizing_antibody: low       # ex-vivo use avoids humoral neutralisation
+      innate_immune: low               # ex-vivo
+      adaptive_immune: low             # ex-vivo
+      genotoxicity: moderate           # INTEGRATING: insertional-mutagenesis risk; SIN-LTR + gene-body bias reduce but do not eliminate it (gamma-retro LMO2 precedent)
+      efficacy: high                   # efficient, STABLE integration; large-ish cargo (~8 kb); transduces non-dividing cells
+      tradeoff: "highly efficacious STABLE integration BUT insertional-mutagenesis / genotoxicity is the dominant safety concern (mitigated by SIN design, not eliminated)"
+      immune_dois: ["10.1038/s41375-018-0106-0", "10.1038/nbt1216", "10.1126/science.1088547"]
+
+  helper_dependent_adenovirus:
+    cargo_capacity_bp: 35000      # "gutless" HDAd, up to ~35 kb
+    integrating: false
+    division_dependent: false
+    immunogenicity_prior: "high (innate + adaptive)"
+    re_dosable: false
+    tropism: "liver and others"
+    in_vivo: true
+    compatible_cargo_form: [DNA]
+    constraint_key: plasmid
+    dois: ["10.1128/JVI.72.2.926-933.1998"]   # multiply-deleted (gutless-class) adenovirus vectors
+    immune_safety:
+      preexisting_immunity: high       # widespread prior adenovirus exposure in the population
+      neutralizing_antibody: high      # anti-Ad NAbs common; limit systemic in-vivo dosing
+      innate_immune: high              # potent acute innate/inflammatory response to the capsid
+      adaptive_immune: high            # strong anti-vector adaptive response
+      genotoxicity: low                # non-integrating, episomal "gutless" genome
+      efficacy: high                   # very large cargo (~35 kb), efficient hepatic transduction
+      tradeoff: "huge cargo + non-integrating BUT strong innate+adaptive anti-Ad immunity and pre-existing NAbs are the dominant safety limit for systemic use"
+      immune_dois: ["10.1089/hum.2004.15.1157"]
+
+  hsv_amplicon:
+    cargo_capacity_bp: 100000     # >100 kb
+    integrating: false
+    division_dependent: false
+    immunogenicity_prior: "high; neurotropic"
+    re_dosable: false
+    tropism: "neurotropic (CNS)"
+    in_vivo: true
+    compatible_cargo_form: [DNA]
+    constraint_key: plasmid
+    dois: ["10.1038/nbt1101-1067"]   # Wade-Martins 2001, HSV-1 amplicon (iBAC) large genomic-DNA transfer
+    immune_safety:
+      preexisting_immunity: moderate   # prior HSV exposure common, but helper-free amplicon is gene-free of HSV ORFs
+      neutralizing_antibody: moderate  # anti-HSV humoral immunity in seropositive hosts
+      innate_immune: high              # immunogenic / inflammatory in CNS
+      adaptive_immune: high
+      genotoxicity: low                # non-integrating, episomal
+      efficacy: moderate               # massive cargo (>100 kb) + neurotropism, but transient/variable expression
+      tradeoff: "unmatched cargo (>100 kb) and CNS tropism BUT immunogenic/inflammatory and expression is transient"
+      immune_dois: ["10.1089/hum.2004.15.1157"]
+
+  lnp_mrna:
+    cargo_capacity_bp: 15000      # large RNA payload (mRNA encoding the writer/RNP)
+    integrating: false            # transient
+    division_dependent: false
+    immunogenicity_prior: "low/transient"
+    re_dosable: true
+    tropism: "liver-tropic by default"
+    in_vivo: true
+    compatible_cargo_form: [mRNA, RNP]
+    constraint_key: lnp_mrna
+    dois: ["10.1038/s41578-021-00358-0"]
+    immune_safety:
+      preexisting_immunity: low        # no widespread pre-existing immunity to the LNP (anti-PEG is an emerging exception)
+      neutralizing_antibody: low       # anti-PEG antibodies emerging; can accelerate clearance on repeat dosing
+      innate_immune: moderate          # transient innate sensing of mRNA / ionizable lipid (mitigated by mod-nucleosides)
+      adaptive_immune: low             # no anti-vector adaptive memory to a protein capsid
+      genotoxicity: low                # NON-integrating, transient (no insertional risk)
+      efficacy: moderate               # transient expression; potent for hepatic RNP/mRNA but durability is short
+      re_dosable: yes                  # repeatable dosing is the key advantage
+      tradeoff: "SAFEST profile (non-integrating, transient, re-dosable, low pre-existing immunity) BUT expression is transient and anti-PEG immunity can blunt repeat doses"
+      immune_dois: ["10.1016/j.addr.2020.07.024"]
+
+  evlp:
+    cargo_capacity_bp: null       # RNP payload (not a DNA packaging limit)
+    integrating: false
+    division_dependent: false
+    immunogenicity_prior: "low (transient, no DNA)"
+    re_dosable: true
+    tropism: "engineerable (T cells, retina)"
+    in_vivo: true
+    ex_vivo: true
+    compatible_cargo_form: [RNP]
+    constraint_key: evlp
+    dois: ["10.1016/j.cell.2022.03.045"]
+    immune_safety:
+      preexisting_immunity: low        # protein/RNP payload, no viral capsid; transient
+      neutralizing_antibody: low
+      innate_immune: low               # no DNA, transient delivery
+      adaptive_immune: low
+      genotoxicity: low                # non-integrating RNP, transient nuclease exposure
+      efficacy: moderate               # engineerable tropism; emerging modality, in-vivo efficiency still maturing
+      re_dosable: yes
+      tradeoff: "low-immunogenicity transient RNP delivery with engineerable tropism BUT an emerging modality with still-maturing in-vivo efficiency"
+      immune_dois: ["10.1016/j.ymthe.2019.12.010"]
+
+  electroporation:
+    cargo_capacity_bp: null       # physical; no packaging limit
+    integrating: false            # depends on cargo
+    division_dependent: false
+    immunogenicity_prior: "n/a (ex vivo)"
+    re_dosable: false
+    tropism: "n/a (ex vivo)"
+    ex_vivo: true
+    compatible_cargo_form: [DNA, mRNA, RNP]
+    constraint_key: electroporation
+    dois: ["10.1038/nprot.2014.157"]
+    immune_safety:
+      preexisting_immunity: low        # ex-vivo, physical method; no vector immunology
+      neutralizing_antibody: low       # ex-vivo (n/a in host)
+      innate_immune: low               # ex-vivo
+      adaptive_immune: low             # ex-vivo
+      genotoxicity: low                # cargo-dependent; RNP/transient cargo carries no insertional risk
+      efficacy: high                   # high ex-vivo delivery efficiency across DNA/mRNA/RNP
+      tradeoff: "no vector immunology and high ex-vivo efficiency BUT EX-VIVO ONLY (cell harvest/manufacture required) and cytotoxic at high field strength"
+      immune_dois: ["10.1016/j.ymthe.2019.12.010"]

pen_stack-5.1.0/docs/co_scientist.md

@@ -0,0 +1,31 @@
+# The co-scientist (v5.0)
+
+v5.0 matures the reasoning layer on top of the verifier (v3.3), the environment (v3.4), the oracle mesh
+(v4.0), and the living world-model (v4.5). Give it a goal and an intent and it returns a small set of
+**materially distinct, ranked, fully-traceable strategies** — each verified, calibrated, cited, and
+scope-ledgered — while the **no-fabrication guarantee holds by construction**: the reasoning layer proposes
+and critiques, but every number still comes from a validated tool or oracle.
+
+> **The central invariant.** Intelligence rises while groundedness never falls. A test asserts no-fabrication
+> across the *full* reasoning stack (`pen_stack/validate/bench_coscientist_tasks.py`).
+
+## What it does (`pen_stack/agent/co_scientist.py`, `pen_stack/agent/cite.py`)
+
+| Capability | Function | Guarantee |
+|---|---|---|
+| **Multiple distinct strategies** | `propose_strategies(goal)` | 2–3 strategies differing on ≥2 design axes (write-type / writer / delivery / intent) — *materially* distinct, not reworded (`distinctness()` measures it); each independently **legal** + **confidence-tagged** |
+| **Deliberative planning** | `deliberate(goal)` | the deliberative planner vs the deterministic `pen_agent` baseline, head-to-head; both grounded |
+| **Self-critique / revise** | `critique_and_revise(design)` | the critic only flags + suggests a design-level swap (never invents a number); the revision is **re-verified**; falsifiable — it improves flawed plans (illegal→legal) and never spuriously touches clean ones (`critique_falsifiability()`) |
+| **Cited rationale** | `cited_rationale(design)` | the "why" cites DOIs **drawn from the curated world-model** (so they resolve by construction); a hallucinated-citation guard rejects any DOI not in the curated set |
+| **Scope ledger** | `scope_ledger(design)` | per recommendation, an itemised list of what **was** assessed (legality / reachability / delivery / payload / calibrated confidence) and what was **not** (the standing known-unknowns) — never silently omitted |
+| **Scoped generalisation** | `generalise(task)` | adjacent genetic-engineering tasks are **grounded-or-refused**: answered only if they map to an existing grounded capability, otherwise refused with a scope statement |
+
+## Honest scope
+
+A better reasoner is **not a complete model of the cell**. structure→phenotype, in-vivo behaviour,
+immunogenicity magnitude, long-term durability and higher-order epistasis remain out of scope — the
+co-scientist makes that boundary *legible* (the scope ledger), it does not close it. Self-critique and
+multi-strategy ship only because they help on held-out checks, or are reported as not-yet-useful.
+Generalisation is approached only as far as the grounding allows; the rest is refused, not faked.
+
+See `prereg/ws_{plan,crit,cite}.yaml` and the `co_scientist_grounded` bench task (Genome-Writing Bench v0.3.2).

{pen_stack-4.5.1 → pen_stack-5.1.0}/pen_stack/__init__.py

@@ -1,2 +1,2 @@
 """PEN-STACK v3.0 - open infrastructure for genome writing."""
-__version__ = "4.5.1"
+__version__ = "5.1.0"