Specifications
OpenOnco is a specifications-first project. Every architectural, clinical, and governance detail is pinned in a markdown document under specs/ that is versioned and open to public review. 10 active specifications cover everything from FDA non-device CDS positioning to the shape of every YAML entity in the KB. The full text lives at github.com/romeo111/OpenOnco/specs.
specs/*.md → 3. CLAUDE.md → 4. README.md. Anything under legacy/ is not authoritative.
Active specifications (10)
CHARTER.md
Charter & Governance
Project governance, scope (what it does and what it explicitly does not), FDA non-device CDS positioning (§15 with constraints C1-C7), the two-reviewer rule for clinical content (§6.1), patient-data privacy (§9.3), forbidden prompt patterns for LLMs (§8.3 — LLMs do not make clinical decisions).
CLINICAL_CONTENT_STANDARDS.md
Clinical Content Standards
Clinical content standards: citation format (source_id + position + paraphrase + page), evidence-level taxonomy (Tier 1-6), reviewer sign-off workflow, STUB → reviewed transition criteria. Every claim in an Indication / Regimen / RedFlag links to a Source entity.
DATA_STANDARDS.md
Data Standards — Patient Model
Patient profile data model. FHIR R4/R5 + mCODE alignment on the roadmap. Code systems: LOINC + ICD-10/O-3 + RxNorm + CTCAE v5.0. No SNOMED CT and no MedDRA in the MVP (license gates). Profile fields and semantic interoperability.
KNOWLEDGE_SCHEMA_SPECIFICATION.md
Knowledge Schema Specification
Pydantic schemas for every KB entity — Disease / Indication / Regimen / Algorithm / Biomarker / Drug / Test / Workup / RedFlag / Contraindication / MonitoringSchedule / SupportiveCare / Source. Defines fields, validators, referential-integrity rules, and the migration roadmap to PostgreSQL.
SOURCE_INGESTION_SPEC.md
Source Ingestion & Licensing
How we ingest sources: the hosting matrix (referenced vs hosted vs mixed) with H1-H5 justification, license-classification gates, the add-a-source checklist (§8), the hosted-source checklist (§20), and the SourceClient protocol for live APIs.
REFERENCE_CASE_SPECIFICATION.md
Reference Case — "Patient Zero"
A synthetic HCV-MZL reference case as the P0 acceptance test. Defines every required patient-profile field (§2 templates), the critical structural assertions for Plan render output (§1.3), and milestones M1-M6 for expanding coverage.
MDT_ORCHESTRATOR_SPEC.md
MDT Orchestrator + Decision Provenance
Orchestrate_mdt rules (R1-R9 for treatment, D1-D6 for diagnostic), role activation logic (required / recommended / optional), the Open Questions mechanism (Q1-Q6 + DQ1-DQ4 — the engine refuses to decide without the required data), and a decision-provenance graph for audit-grade explanation.
DIAGNOSTIC_MDT_SPEC.md
Diagnostic-Phase MDT (Pre-biopsy)
Pre-biopsy mode: when histology is not yet available the engine emits a DiagnosticPlan with a workup brief instead of a treatment Plan. CHARTER §15.2 C7 hard rule. DiagnosticWorkup + DiagnosticPlan schemas, generate_diagnostic_brief(), polymorphic orchestrate_mdt with DQ1-DQ4 rules.
WORKUP_METHODOLOGY_SPEC.md
Workup Research Methodology
How we build a basic workup for any oncology area. Source hierarchy (Tier 1: NCCN/ESMO/EHA/BSH/WHO/ASH), Test/Workup completeness checklists, the 7-step process for extending coverage to a new domain, anti-patterns.
SKILL_ARCHITECTURE_SPEC.md
Skill-Oriented Architecture (MDT Roles as Skills)
Formalises MDT roles (haematologist / pathologist / radiologist / etc.) as clinically-verified skills — each skill carries version, sources, last_reviewed, clinical_lead. Sizing horizon (~12-15 MVP → 50-60 comprehensive), 8-domain layout, 5-phase refactor plan.
Regulatory source (PDF)
Guidance-Clinical-Decision-Software_5.pdf
FDA Clinical Decision Support Software Guidance
The official FDA guidance on non-device CDS classification under §520(o)(1)(E). Hosted under specs/ as a PDF. CHARTER §15 cites concrete criteria 1-4 from this document to justify OpenOnco's non-device positioning.
How we update the specifications
Any change under specs/ or knowledge_base/hosted/content/ that affects clinical recommendations requires a two-reviewer merge (CHARTER §6.1) — two of three Clinical Co-Lead approvals. This is the hard rule that gates clinical-content quality. Technical specs (schemas, engine, ingestion) can merge with a single reviewer to keep development moving, but clinical content always needs dual sign-off.
All specifications are written Ukrainian-first (the interface and the clinical reviewers are UA), but technical terms and license names stay in English inline. Versioning is via git: every spec carries v0.1 (draft) in the header and is bumped on minor/major depending on breaking changes.
Compliance + privacy (quick view)
| Guarantee | Specification | What it means |
|---|---|---|
| FDA non-device CDS | CHARTER.md §15 |
OpenOnco is designed for the §520(o)(1)(E) carve-out — not a medical device. Constraints C1-C7 are hard-enforced. |
| No patient data | CHARTER.md §9.3 |
patient_plans/ and any patient HTML are gitignored. All examples are synthetic. |
| Two-reviewer merge | CHARTER.md §6.1 |
Clinical content needs 2 of 3 Clinical Co-Lead approvals; otherwise the Indication stays STUB. |
| No LLM clinical judgment | CHARTER.md §8.3 |
LLMs do not pick regimens, do not generate doses, and do not interpret biomarkers for therapy selection. |
| No treatment without histology | CHARTER.md §15.2 C7 |
The engine refuses to generate a treatment Plan without disease.id or icd_o_3_morphology — only a DiagnosticPlan. |
| Anti automation-bias | CHARTER.md §15.2 C6 |
≥2 alternative tracks are always shown side-by-side; the alternative is never hidden. |
| Source hosting default = referenced | SOURCE_INGESTION_SPEC.md §1.4 |
We do not duplicate external databases; hosting requires explicit H1-H5 justification. |
| Free public resource → non-commercial | CHARTER.md §2 |
Many licences (ESMO CC-BY-NC-ND, OncoKB academic, ATC) depend on this. A paid tier would trigger a license audit. |