Initial public snapshot

Author: jvogan

.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.{json,yml,yaml,md}]
+indent_style = space
+indent_size = 2
+
+[Makefile]
+indent_style = tab

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,37 @@
+---
+name: Bug report
+about: Validator, schema, or CLI behaves incorrectly
+title: "[bug] "
+labels: ["bug"]
+---
+
+## What happened
+
+What did `ferm-doe validate` (or another command) return that you didn't expect?
+
+## What you expected
+
+What should it have done instead?
+
+## Reproduction
+
+Minimal manifest or shell session. Use synthetic / public-safe data only; do not paste private process data, strain details, or unpublished sequences. If the bug only reproduces with private data, describe the shape, not the contents.
+
+```bash
+ferm-doe validate <campaign_dir> --summary
+```
+
+```json
+{ ... minimal manifest ... }
+```
+
+## Environment
+
+- `biosymphony-ferm-doe` version (or commit SHA):
+- Python version:
+- OS:
+- Agent harness (Claude Code / OpenAI Agents / Codex / generic / standalone):
+
+## Additional context
+
+Profile(s) declared, claim_level, anything else useful.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,26 @@
+---
+name: Feature request
+about: Propose new validator behavior, schema slot, or CLI affordance
+title: "[feature] "
+labels: ["enhancement"]
+---
+
+## Problem
+
+What does a long-running agent (or scientist) need to do today that the skill makes harder than it should?
+
+## Proposed change
+
+What would the schema, validator, or CLI look like after the change? Be specific.
+
+## Alternatives considered
+
+Including: doing nothing, doing it in the agent's own code instead of the skill, or punting to a future profile.
+
+## Public-safety considerations
+
+Does the change require new public-safety rules (e.g., a new `claim_level` value)? New input categories?
+
+## Non-goals
+
+What this change should *not* do. Helps keep scope tight.

.github/ISSUE_TEMPLATE/new_doe_family.md

@@ -0,0 +1,42 @@
+---
+name: New DoE family
+about: Propose a new design family
+title: "[family] "
+labels: ["family-proposal"]
+---
+
+## Family name
+
+Snake_case (`d_optimal_with_blocks`, `mixture_process_combined`, etc.).
+
+## When to use
+
+What problem does this family solve that the current set does not?
+
+## Reference
+
+Standard reference (Montgomery, Jones & Nachtsheim, Cornell, Box-Hunter-Hunter, etc.). DOI or canonical link.
+
+## Minimum-runs formula
+
+Closed form if computable; "user_declared" if it depends on parameters the schema does not carry.
+
+## Required structural fields
+
+Resolution? Alias structure? Mixture components? Hard-to-change factors? Previous wave reference?
+
+## Replication / center-point expectations
+
+What does a well-formed instance of this family include?
+
+## Statistical claim level
+
+What `doe.claim` value should default for this family: `exact`, `adapter_backed`, `approximate`, or `heuristic`?
+
+## Validator behavior
+
+What checks would the validator run against a manifest declaring this family? Each check id and severity (warning vs error).
+
+## Adapter
+
+If a DoE adapter (statsmodels, pyDOE3, custom) generates this family today, link it. If not, note that.

.github/ISSUE_TEMPLATE/new_profile.md

@@ -0,0 +1,46 @@
+---
+name: New profile
+about: Propose a new campaign profile
+title: "[profile] "
+labels: ["profile-proposal"]
+---
+
+## Profile name
+
+Snake_case, descriptive, verb-or-noun-shaped (`scale_down_qualification`, `sequential_augmentation`, `confirmation`).
+
+## When to use
+
+Concrete scenarios. At least three.
+
+## Required blocks
+
+What manifest blocks become errors when absent under this profile? Keep this list short; required blocks should reflect structural inability to do what the profile claims.
+
+## Advised blocks
+
+What blocks emit warnings when absent? Most things go here.
+
+## Advised inputs
+
+What input files does this profile expect to consume?
+
+## Advised expected artifacts
+
+What outputs should the agent produce by default?
+
+## Default DoE families
+
+Which design families fit this profile? List 2-4.
+
+## Profile-specific structural requirements
+
+Anything else unique to this profile? E.g., `factor_hard_to_change_required`, `recapitulation_criterion_required`, `previous_wave_ref_required`.
+
+## Public demo
+
+Do you intend to ship a `examples/demo-<profile>-public/` campaign with this profile? If yes, sketch what it would show.
+
+## Why not extend an existing profile
+
+Why is this a new profile rather than a variant of `screening`, `optimization_rsm`, or `custom`?

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,33 @@
+## What changed
+
+One-line summary.
+
+## Why
+
+The user-visible problem this PR solves. Link issues / discussions.
+
+## Public-safety checklist
+
+- [ ] No private strain details, sequences, customer data, or confidential formulations.
+- [ ] No API keys, tokens, or credentials.
+- [ ] No private workstation paths or private issue/team identifiers.
+- [ ] Synthetic / public-source rows are clearly labeled.
+- [ ] `make release-check` passes.
+- [ ] `make secret-scan` passes (or gracefully reports gitleaks not installed).
+
+## Validator / schema impact
+
+- [ ] No schema change.
+- [ ] Schema change is backwards-compatible (adds optional fields only).
+- [ ] Schema change is breaking; `CHANGELOG.md` updated under a clearly-labeled breaking-changes section.
+
+## Demo impact
+
+- [ ] No demo changes.
+- [ ] Existing demos still validate to expected verdicts.
+- [ ] New demo added under `examples/demo-<name>-public/`.
+
+## Long-running agent impact
+
+- [ ] No agent-facing change.
+- [ ] `SKILL.md` / `agents/*.md` updated where the loop, refuse-vs-warn, or hand-off behavior changes.

.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package
+        run: python -m pip install -e .
+      - name: Run public release gate
+        run: make release-check
+
+  secret-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Install gitleaks
+        env:
+          GITLEAKS_VERSION: "8.30.0"
+        run: |
+          set -euo pipefail
+          curl -fsSL "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" -o /tmp/gitleaks.tar.gz
+          tar -xzf /tmp/gitleaks.tar.gz -C /tmp gitleaks
+          sudo install -m 0755 /tmp/gitleaks /usr/local/bin/gitleaks
+          gitleaks version
+      - name: Run gitleaks
+        run: make secret-scan-required

.gitignore

@@ -0,0 +1,28 @@
+.DS_Store
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+.env
+.runtime/
+.nox/
+.coverage
+htmlcov/
+.ipynb_checkpoints/
+dist/
+build/
+*.egg-info/
+ferm-doe-dossier/
+ferm-doe-dossier-*/
+.aws-sam/
+samconfig.toml
+samconfig.*.toml
+packaged.yaml
+packaged-template.yaml
+deploy/aws-lambda/.aws-sam/
+deploy/aws-lambda/packaged*.yaml
+deploy/aws-lambda/*-packaged.yaml
+.serverless/

AGENTS.md

@@ -0,0 +1,90 @@
+# BioSymphony Ferm DoE Public Repo Agent Guide
+
+Public workspace for BioSymphony Ferm DoE.
+
+## Mission
+
+Help users and their agents drive long-horizon, multi-agent bioprocess design campaigns from intake through Wave 2. The repo is a skill any agent harness can pick up: Symphony with Linear, Claude Code workers with Linear, Codex CLI, OpenAI Agents SDK, or a custom orchestrator, running on a laptop, in CI, or behind AWS Lambda or Modal. The agent and the human share one durable artifact (`campaign_manifest.json`), pause, resume, hand off, and converge on a fermentation campaign that is worth running.
+
+The repo ships:
+
+- profile registry (screening, optimization_rsm, mixture, split_plot_fed_batch, scale_up_bridge, scale_down_qualification, confirmation, sequential_augmentation, custom)
+- scale_context block (multi-criterion: kLa, P/V, tip_speed, mix_time, DO, OUR, RQ, VVM, geometric_similarity, custom)
+- multi-arm (`arms[]`) campaigns
+- per-axis readiness state (responses, factors, arms, scale_context, doe, decision_rules, evidence, feasibility)
+- decision_rules / stop_rules / risk_register / assumptions blocks
+- DoE family taxonomy with minimum-runs guidance
+- a curated 37-tool BO/DoE registry with documented adapter routing (`docs/TOOL_REGISTRY.md`, `docs/tool-registry.json`)
+- BoFire, ENTMOOT v2, OMLT, TabPFN, BoTorch, pyDOE3, SALib, scipy, PubMed MCP adapters that degrade cleanly when the optional extra is absent
+- a cumulative dossier pattern (per-corpus swarm plus integrator plus harvester) backed by `provenance.py` and `rocrate_retrofit.py`
+- a cost-model honesty stack (simulator, bulk reagent, fully-loaded COGS, CMO, range)
+- JSON Schema for the manifest plus Frictionless table contracts for CSV inputs
+- issue-pack and task-request contracts that let an orchestrator fan work across parallel sub-agents and converge results
+- AWS Lambda and Modal scaffolds so the same commands run from a laptop, from CI, or behind a stateless cloud endpoint
+- public-safety audit and validators
+
+## Public Safety Rules
+
+Do not add:
+
+- private strain details
+- unpublished sequences
+- customer batch records
+- confidential media formulations
+- API keys or provider credentials
+- private workstation paths
+- private issue-tracker / team / project identifiers
+- raw private campaign artifacts
+
+Use synthetic or public-source examples only, label synthetic data clearly.
+
+## Current State
+
+- README plus workflow images
+- public-safe `SKILL.md` with long-agent loop
+- canonical `NON_CLAIMS.md`
+- profile registry (9 profiles), scale_bridge framework, DoE family taxonomy (14 families), JSON Schema, table contracts
+- adapters for BoFire, ENTMOOT v2, OMLT, TabPFN, BoTorch, pyDOE3, SALib, scipy, PubMed MCP
+- public demos: twelve campaign-shaped demos covering screening (xylanase, PB screening, warnings-walkthrough), scale_down_qualification (scale-bridge), split_plot_fed_batch, BoFire routes (media cost, shakeflask-to-2L), ENTMOOT NChooseK smoke, multi-arm scale transfer, reference DOE custom design, public-paper starter (xylanase-wxz1-2012), and product-class starter (yeast-isoprenoid-2L-fedbatch); plus the `adaptive-backend-eval` and `starter-studies` auxiliary fixtures
+- reference docs: GLOSSARY, CLI_REFERENCE, ADAPTER_MAP, DOE_FAMILY_RECIPES, WAVE2_BOTORCH, ISSUE_PACK_GENERATION, BACKEND_EVAL_FINDINGS, ADAPTER_DESIGN_NOTES
+- Python package scaffold (stdlib-only at runtime; optional extras route through adapters)
+- AWS Lambda and Modal deploy scaffolds in `deploy/`
+- public-safety tests, per-validator tests, adapter tests, dossier provenance tests; 455 tests pass with 38 expected skips
+
+## Long-Agent Loop
+
+See `skills/biosymphony-ferm-doe/SKILL.md`. Summary: intake, readiness gate, factor framing, scale framing, DoE selection, run packet, Wave 2 review. Refuse on missing required blocks for declared profiles, missing assayed-response contracts, and public-safety violations. Warn on profile-advised gaps and DoE family minimum-runs shortfalls.
+
+## Key Pattern And Convention
+
+- Treat public examples as synthetic contract fixtures, not campaign records.
+- Keep campaign routing explicit through `task_request` contracts; do not activate heavy campaign workflows for ordinary validation or docs tasks.
+- Keep issue packs tracker-neutral until a private campaign maps pack-local IDs to a tracker.
+- Preserve arm scope in DOE artifacts: per-arm executable CSVs are authoritative; horizontal DOE tables are review surfaces.
+- Prefer stdlib/offline code paths in the public package; optional scientific dependencies must degrade cleanly.
+- Bounded workers (parallel sub-agents, swarm corpora, integrator and harvester roles) are coordinated through `task_request` contracts and the cumulative-dossier pattern, not ad-hoc dispatch.
+- One coherent dossier per campaign (`CITATIONS.json`, `NOTES.md`, `SOURCES.bib`, per-corpus `EVIDENCE.csv`), not N isolated reports.
+
+## Risks To Watch
+
+- Do not turn public demos into implied lab-validation or production-readiness claims.
+- Watch for accidental private paths, provider IDs, issue-tracker IDs, private biological details, or copied article tables before release.
+- Keep scale-transfer wording at planning or qualification status unless executed bridge evidence is present.
+- Keep warnings deterministic so public demos remain useful regression fixtures.
+- When BoFire's `SoboStrategy` plus `NChooseK` is requested, route to ENTMOOT v2 or enforce cardinality post-hoc; upstream issue #450 stalls indefinitely.
+- When the simulator drives the planner, declare `simulator.fidelity_level` on the manifest and run the literature pressure-test template before sealing a campaign.
+
+## Next Best Work
+
+1. Keep all demos complete, deterministic, and clearly synthetic; the diagnostic walkthrough should continue to surface intentional guidance warnings.
+2. Extend validators only with public-safe logic and fixtures.
+3. Keep `make release-check` passing before any public push.
+4. Add new demos under public-safe artifact folders when more profiles see use.
+5. Re-run history and tree scans before first remote publication.
+6. When new DoE adapters land, label their claim level and route reason in the tool registry.
+
+## Claim Boundaries
+
+This repo validates measurement readiness, manifest structure, and profile fit before lab work. It does not validate actual lab measurements unless result rows are ingested with provenance and QC evidence.
+
+Do not claim optimized, validated, production-ready, or GxP-ready behavior.