pen-stack 4.5.0__tar.gz → 5.0.0__tar.gz

{pen_stack-4.5.0 → pen_stack-5.0.0}/CHANGELOG.md

@@ -3,6 +3,42 @@
 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.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
+Two of the three new v4.5 Tier-A cell-type ontology IDs in `configs/cell_types.yaml` were wrong (verified via
+EBI-OLS): `EFO:0002322` resolved to the **RPMI8226 myeloma line** (not a T cell) and `EFO:0004146` to an
+**obsolete myopathy term** (not hepatocyte). Corrected to the canonical, non-obsolete Cell Ontology terms:
+**primary_T_cell → `CL:0000084`** (T cell), **hepatocyte → `CL:0000182`** (hepatocyte). iPSC (`EFO:0004905`),
+K562 (`EFO:0002067`), HepG2 (`EFO:0001187`) verified correct, as was the ISPpu10 back-test record (Europe PMC
+**PPR1218813** — "ISPpu10 is a structure-gated bridge RNA recombinase…"). No result/test change (the IDs are
+coverage-card metadata; `cell_types.py` reads coverage, not the ontology id).
+
 ## [4.5.0] - 2026-06-09 - v4.5 release: the Living World-Model (knowledge graph + gated living loop)
 
 v4.5 promotes the flat tables into a queryable knowledge graph that keeps itself current. Workstreams

{pen_stack-4.5.0 → pen_stack-5.0.0}/CITATION.cff

@@ -1,7 +1,7 @@
 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.0
+version: 5.0.0
 date-released: 2026-06-01
 authors:
   - family-names: "Mahaboob Ali"

{pen_stack-4.5.0 → pen_stack-5.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 4.5.0
+Version: 5.0.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
@@ -89,12 +89,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.0-blue.svg)](CHANGELOG.md)
-[![Tests](https://img.shields.io/badge/tests-224%20passing-success.svg)](tests/)
+[![Version](https://img.shields.io/badge/version-5.0.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 +133,23 @@ 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.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 +429,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.0 → pen_stack-5.0.0}/README.md

@@ -14,12 +14,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.0-blue.svg)](CHANGELOG.md)
-[![Tests](https://img.shields.io/badge/tests-224%20passing-success.svg)](tests/)
+[![Version](https://img.shields.io/badge/version-5.0.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 +58,23 @@ 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.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 +354,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.0 → pen_stack-5.0.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.0 → pen_stack-5.0.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-4.5.0 → pen_stack-5.0.0}/configs/cell_types.yaml

@@ -36,13 +36,13 @@ cell_types:
     note: "iPSC/ESC; broad chromatin but TRIP durability not measured here -> durability OOD-labelled, degraded."
   primary_T_cell:
     tier: A
-    efo: "EFO:0002322"        # CD4+/CD8+ primary T cell (CAR-T relevant)
+    ontology: "CL:0000084"    # T cell (Cell Ontology); CAR-T relevant
     coverage: partial
     tracks: [atac, expression]
     note: "primary T cells (CAR-T context); accessibility + expression only -> histone-dependent safety degraded."
   hepatocyte:
     tier: A
-    efo: "EFO:0004146"        # primary hepatocyte
+    ontology: "CL:0000182"    # hepatocyte (Cell Ontology); in-vivo liver target
     coverage: partial
     tracks: [atac, h3k27ac, expression]
     note: "primary hepatocytes (in-vivo liver target); partial panel -> graceful degradation, scope-flagged."

pen_stack-5.0.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.0 → pen_stack-5.0.0}/pen_stack/__init__.py

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

pen_stack-5.0.0/pen_stack/agent/cite.py

@@ -0,0 +1,118 @@
+"""Cited mechanistic rationale + scoped generalisation (v5.0, WS-CITE + WS-GEN).
+
+Every recommendation carries a short, literature-cited "why". Crucially the citations are **drawn from the
+curated world-model** (the verifier rule provenance, the writer/delivery/locus DOIs) — not generated by a
+language model — so they **resolve by construction**. A hallucinated-citation guard rejects any DOI that is
+not in the curated, already-verified set (WS-CITE). Numbers in the rationale remain tool-sourced (the prose is
+a presentation layer over verified facts; no quantity is invented).
+
+WS-GEN: generalisation toward adjacent genetic-engineering tasks is **grounded-or-refused** — a task is
+answered only if it maps to an existing grounded capability; anything else is refused with a scope statement,
+never faked.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+import yaml
+
+from pen_stack._resources import resource
+
+
+@lru_cache(maxsize=1)
+def curated_dois() -> frozenset[str]:
+    """The set of DOIs that appear in the CURATED, already-verified world-model (delivery palette, GSH loci,
+    writer panel, rule provenance). A citation is 'grounded' iff its DOI is in this set — so a citation can
+    only ever point at a source the substrate has actually curated (no hallucinated references)."""
+    dois: set[str] = set()
+    veh = yaml.safe_load(resource("configs/delivery_vehicles.yaml").read_text(encoding="utf-8"))["vehicles"]
+    for v in veh.values():
+        dois.update(v.get("dois", []) or [])
+    gsh = yaml.safe_load(resource("configs/gsh_validated_heldout.yaml").read_text(encoding="utf-8"))["gsh"]
+    for g in gsh:
+        if g.get("doi"):
+            dois.add(g["doi"])
+    import csv
+    with open(resource("data/writer_panel.csv"), encoding="utf-8") as f:
+        for row in csv.DictReader(f):
+            if row.get("doi"):
+                dois.add(row["doi"])
+    # rule provenance DOIs
+    from pen_stack.rules import load_ruleset
+    for r in load_ruleset().rules:
+        dois.update(r.provenance.get("doi", []) or [])
+    return frozenset(dois)
+
+
+def citations_grounded(dois: list[str]) -> dict:
+    """Hallucinated-citation guard: every cited DOI must be in the curated set. Returns the verdict + any
+    ungrounded DOIs (which would be a hallucination and are rejected)."""
+    curated = curated_dois()
+    ungrounded = [d for d in dois if d not in curated]
+    return {"all_grounded": not ungrounded, "ungrounded": ungrounded, "n_checked": len(dois)}
+
+
+def cited_rationale(design: dict) -> dict:
+    """A short, literature-cited mechanistic 'why' for a design, with citations DRAWN FROM the curated
+    world-model (so they resolve by construction). Numbers are tool-sourced; the prose is presentation only."""
+    from pen_stack.graph import build_graph
+    from pen_stack.verify import verify
+    g = build_graph()
+    v = verify(design)
+    fam = design.get("writer_family")
+    veh = design.get("delivery_vehicle")
+    cites: list[dict] = []
+    wnode = g.nodes.get(f"writer:{fam}")
+    if wnode:
+        for d in wnode.props.get("dois", [])[:1]:
+            cites.append({"doi": d, "claim": f"{fam} mechanism / characterisation", "source": "world-model writer"})
+    vnode = g.nodes.get(f"vehicle:{veh}")
+    if vnode:
+        for d in vnode.props.get("dois", [])[:1]:
+            cites.append({"doi": d, "claim": f"{veh} delivery properties", "source": "world-model vehicle"})
+    form = wnode.props.get("output_form") if wnode else None
+    verdict = "legal" if v.legal else "illegal"
+    rationale = (f"{fam} ({form}-form) installs a {design.get('cargo_bp')} bp cargo via {veh}; the rule-grounded "
+                 f"verifier judges this {verdict}"
+                 + (f" (violated: {', '.join(x['rule_id'] for x in v.violations)})" if not v.legal else "")
+                 + (f"; calibrated confidence {v.confidence}" if v.confidence is not None else
+                    "; confidence abstained (unscored)") + ".")
+    guard = citations_grounded([c["doi"] for c in cites])
+    return {"design": {k: val for k, val in design.items() if not str(k).startswith("_")},
+            "rationale": rationale, "citations": cites, "n_citations": len(cites),
+            "citations_grounded": guard["all_grounded"], "ungrounded_citations": guard["ungrounded"],
+            "no_fabrication": v.no_fabrication and guard["all_grounded"],
+            "note": "citations are drawn from the curated world-model (resolve by construction); numbers are "
+                    "verifier-sourced; the prose is a presentation layer (no fabricated quantity)."}
+
+
+# --------------------------------------------------------------------------------------------------
+# WS-GEN - scoped generalisation: grounded-or-refused.
+# --------------------------------------------------------------------------------------------------
+# adjacent genetic-engineering tasks that MAP to an existing grounded capability (answerable);
+# anything else is refused with a scope statement.
+_GROUNDED_TASKS = {
+    "delivery_selection": "maps to the v3.3 delivery rules (cargo-form + capacity + integration)",
+    "write_type_legality": "maps to the v3.3 write-type router + verifier",
+    "off_target_screen": "maps to the bridge off-target engine (a screen, not a per-site calculator)",
+    "writer_variant_critique": "maps to the v4.0 writer-verification branch (score/critique, never invent)",
+}
+
+
+def generalise(task: str, payload: dict | None = None) -> dict:
+    """Answer an adjacent genetic-engineering task ONLY if it maps to a grounded capability; otherwise REFUSE
+    with a scope statement (Principle 4: grounded-or-refused, never faked)."""
+    payload = payload or {}
+    if task not in _GROUNDED_TASKS:
+        return {"task": task, "grounded": False, "refused": True,
+                "scope_statement": f"'{task}' has no grounding in PEN-STACK; refused rather than faked. "
+                                   f"Grounded tasks: {sorted(_GROUNDED_TASKS)}.",
+                "no_fabrication": True}
+    result: dict = {"task": task, "grounded": True, "refused": False,
+                    "grounding": _GROUNDED_TASKS[task], "no_fabrication": True}
+    if task in ("delivery_selection", "write_type_legality") and payload:
+        from pen_stack.verify import verify
+        v = verify(payload)
+        result["verdict"] = {"legal": v.legal, "confidence": v.confidence,
+                             "violations": [x["rule_id"] for x in v.violations]}
+    return result