Специфікації

OpenOnco — це specifications-first проект. Кожна архітектурна, клінічна, або governance деталь зафіксована у markdown-документі під specs/, який підлягає версіонуванню та public review. 10 активних специфікацій описують все: від FDA non-device CDS positioning до структури кожної YAML entity у KB. Усі тексти живуть у github.com/romeo111/OpenOnco/specs.

Source-of-truth ієрархія (з CLAUDE.md): коли специфікації конфліктують, обов'язковий порядок: 1. CHARTER.md → 2. інші specs/*.md → 3. CLAUDE.md → 4. README.md. Контент під legacy/ не authoritative.

Активні специфікації (10)

Governance CHARTER.md

Charter та Governance

Управління проектом, scope (що проект робить і чого не робить), FDA non-device CDS positioning (§15 з constraints C1-C7), two-reviewer rule для clinical content (§6.1), patient-data privacy (§9.3), forbidden prompt patterns для LLM (§8.3 — LLM не приймає клінічні рішення).

Read on GitHub → Raw markdown

Clinical CLINICAL_CONTENT_STANDARDS.md

Clinical Content Standards

Стандарти клінічного контенту: citation format (source_id + position + paraphrase + page), evidence-level taxonomy (Tier 1-6), reviewer signoff workflow, STUB → reviewed transition criteria. Кожна claim у Indication / Regimen / RedFlag має посилання на Source entity.

Read on GitHub → Raw markdown

Data DATA_STANDARDS.md

Data Standards — Patient Model

Patient profile data model. FHIR R4/R5 + mCODE alignment у плані. Кодові системи: LOINC + ICD-10/O-3 + RxNorm + CTCAE v5.0. Без SNOMED CT, без MedDRA у MVP (license gates). Поля профілю та semantic interoperability.

Read on GitHub → Raw markdown

Schema KNOWLEDGE_SCHEMA_SPECIFICATION.md

Knowledge Schema Specification

Pydantic schemas всіх KB entities — Disease / Indication / Regimen / Algorithm / Biomarker / Drug / Test / Workup / RedFlag / Contraindication / MonitoringSchedule / SupportiveCare / Source. Defines fields, validators, referential integrity rules, migration roadmap до PostgreSQL.

Read on GitHub → Raw markdown

Sources SOURCE_INGESTION_SPEC.md

Source Ingestion & Licensing

Як інгестимо джерела: hosting matrix (referenced vs hosted vs mixed) з H1-H5 justification, license classification gates, add-a-source checklist (§8), hosted-source checklist (§20), SourceClient protocol для live APIs.

Read on GitHub → Raw markdown

Testing REFERENCE_CASE_SPECIFICATION.md

Reference Case — "Patient Zero"

Synthetic HCV-MZL reference case як P0 acceptance test. Defines всі required fields у patient profile (§2 templates), critical structural assertions для Plan render output (§1.3), milestones M1-M6 для розширення coverage.

Read on GitHub → Raw markdown

Engine MDT_ORCHESTRATOR_SPEC.md

MDT Orchestrator + Decision Provenance

Orchestrate_mdt rules (R1-R9 для treatment, D1-D6 для diagnostic), role activation logic (required / recommended / optional), Open Questions механізм (Q1-Q6 + DQ1-DQ4 — engine не приймає рішення без потрібних даних), decision provenance graph для audit-grade explanation.

Read on GitHub → Raw markdown

Engine DIAGNOSTIC_MDT_SPEC.md

Diagnostic-Phase MDT (Pre-biopsy)

Pre-biopsy режим: коли histology ще немає, engine emit DiagnosticPlan з workup brief замість treatment Plan. CHARTER §15.2 C7 hard rule. DiagnosticWorkup + DiagnosticPlan schemas, generate_diagnostic_brief(), polymorphic orchestrate_mdt з DQ1-DQ4 rules.

Read on GitHub → Raw markdown

Clinical WORKUP_METHODOLOGY_SPEC.md

Workup Research Methodology

Як ми будуємо basic workup для будь-якої онкологічної області. Source hierarchy (Tier 1: NCCN/ESMO/EHA/BSH/WHO/ASH), Test/Workup completeness checklists, 7-step process для нової domain extension, anti-patterns.

Read on GitHub → Raw markdown

Engine SKILL_ARCHITECTURE_SPEC.md

Skill-Oriented Architecture (MDT Roles as Skills)

Formalізує MDT ролі (гематолог / патолог / радіолог / etc.) як clinically-verified skills — кожен skill має version, sources, last_reviewed, clinical_lead. Sizing horizon (~12-15 MVP → 50-60 comprehensive), 8-domain layout, 5-phase refactor plan.

Read on GitHub → Raw markdown

Регуляторне джерело (PDF)

Regulatory PDF Guidance-Clinical-Decision-Software_5.pdf

FDA Clinical Decision Support Software Guidance

Офіційне керівництво FDA про non-device CDS classification under §520(o)(1)(E). Лежить у specs/ як hosted PDF. CHARTER §15 цитує конкретні criteria 1-4 з цього документа для обґрунтування OpenOnco positioning як non-device.

View PDF on GitHub →

Як ми оновлюємо специфікації

Кожна зміна під specs/ або knowledge_base/hosted/content/ що affects clinical recommendations потребує two-reviewer merge (CHARTER §6.1) — два з трьох Clinical Co-Lead approvals. Це жорстке правило gатекіпить якість клінічного контенту. Технічні специфікації (схеми, engine, ingestion) можуть merge'итися single-reviewer для прискорення розробки, але clinical content — завжди dual sign-off.

Усі специфікації Ukrainian-first (мова інтерфейсу + клінічних reviewers UA), але technical terms та license names залишаються English inline. Версіонування — через git: кожна специфікація має v0.1 (draft) у header, bump на minor/major залежно від breaking changes.

Compliance + Privacy (короткий зріз)

Гарантія	Specification	Що це означає
FDA non-device CDS	`CHARTER.md §15`	OpenOnco проектується під §520(o)(1)(E) carve-out — не медичний пристрій. Constraints C1-C7 hard-enforced.
No patient data	`CHARTER.md §9.3`	`patient_plans/` + будь-які patient HTML gitignored. Усі examples — synthetic.
Two-reviewer merge	`CHARTER.md §6.1`	Clinical content потребує 2 з 3 Clinical Co-Lead approvals; інакше Indication залишається STUB.
No LLM clinical judgment	`CHARTER.md §8.3`	LLM не вибирає режими, не генерує дози, не інтерпретує biomarkers для therapy selection.
No treatment without histology	`CHARTER.md §15.2 C7`	Engine відмовляється generate'ити treatment Plan без `disease.id` або `icd_o_3_morphology`; тільки DiagnosticPlan.
Anti automation-bias	`CHARTER.md §15.2 C6`	Завжди показуються ≥2 alternative tracks side-by-side; alternative не сховано.
Source hosting default = referenced	`SOURCE_INGESTION_SPEC.md §1.4`	Не дублюємо external бази; hosting потребує explicit H1-H5 justification.
Free public resource → non-commercial	`CHARTER.md §2`	Багато ліцензій (ESMO CC-BY-NC-ND, OncoKB academic, ATC) залежать від цього. Paid tier тригернув би license audit.