@pikaa-ai/pikaa 0.2.4 → 0.3.0

package/skills/clinical-reports/assets/quality_review_checklist.json

@@ -0,0 +1,34 @@
+{
+  "schema_version": "2.0",
+  "artifact_kind": "clinical_report_quality_review",
+  "review_status": "BLOCKED_NOT_ASSESSED",
+  "safety_notice": "A completed checklist records review activity only. It does not prove clinical correctness, compliance, approval, or readiness for signature, filing, publication, or submission.",
+  "artifact_reference": null,
+  "artifact_kind_reviewed": null,
+  "guidance_and_version": [],
+  "checks": {
+    "allowed_data_class_confirmed": "not_assessed",
+    "authorized_purpose_confirmed": "not_assessed",
+    "minimum_necessary_confirmed": "not_assessed",
+    "draft_warning_present": "not_assessed",
+    "required_structure_present": "not_assessed",
+    "all_populated_fields_have_verified_fact_ids": "not_assessed",
+    "unsupported_claims_absent": "not_assessed",
+    "source_conflicts_exposed": "not_assessed",
+    "dates_and_chronology_checked": "not_assessed",
+    "units_and_precision_checked": "not_assessed",
+    "counts_denominators_and_percentages_checked": "not_assessed",
+    "missingness_and_suppression_disclosed": "not_assessed",
+    "terminology_versions_recorded": "not_assessed",
+    "privacy_process_reviewed": "not_assessed",
+    "consent_authorization_or_ethics_status_verified_if_applicable": "not_assessed",
+    "clinical_specialist_review_completed": "not_assessed",
+    "statistical_review_completed_if_applicable": "not_assessed",
+    "safety_review_completed_if_applicable": "not_assessed",
+    "privacy_legal_review_completed": "not_assessed",
+    "regulatory_or_journal_review_completed_if_applicable": "not_assessed"
+  },
+  "unresolved_items": [],
+  "review_record_references": [],
+  "release_or_submission_authorized": false
+}

package/skills/clinical-reports/assets/radiology_report_template.json

@@ -0,0 +1,34 @@
+{
+  "schema_version": "2.0",
+  "artifact_kind": "radiology_report_scaffold",
+  "draft_status": "BLOCKED_INCOMPLETE_DRAFT_NOT_FOR_CLINICAL_USE_OR_SIGNATURE",
+  "safety_notice": "This scaffold cannot interpret images or author findings, impressions, urgency, or recommendations. A qualified radiologist must author and sign the report in an authorized clinical system.",
+  "data_classification": null,
+  "authorized_purpose": null,
+  "authorization_verified": false,
+  "guidance": {
+    "base": "ACR Practice Parameter for Communication of Diagnostic Imaging Findings",
+    "revision": "2025",
+    "modality_specific_source": null,
+    "local_policy_version": null
+  },
+  "report_status": null,
+  "source_system_record": null,
+  "fields": {
+    "examination": {"status": "missing", "source_fact_ids": []},
+    "clinical_indication": {"status": "missing", "source_fact_ids": []},
+    "technique_and_limitations": {"status": "missing", "source_fact_ids": []},
+    "comparison": {"status": "missing", "source_fact_ids": []},
+    "findings_authored_by_radiologist": {"status": "missing", "source_fact_ids": []},
+    "impression_authored_by_radiologist": {"status": "missing", "source_fact_ids": []},
+    "nonroutine_communication_record": {"status": "missing", "source_fact_ids": []},
+    "correction_or_addendum_linkage": {"status": "missing", "source_fact_ids": []}
+  },
+  "provenance_manifest": null,
+  "review": {
+    "qualified_radiologist_review": "pending",
+    "privacy_review": "pending",
+    "final_report_created_in_authorized_system": false,
+    "signature_present": false
+  }
+}

package/skills/clinical-reports/assets/research_summary_template.json

@@ -0,0 +1,36 @@
+{
+  "schema_version": "2.0",
+  "artifact_kind": "aggregate_clinical_research_summary_draft",
+  "draft_status": "BLOCKED_INCOMPLETE_DRAFT_NOT_FOR_CLINICAL_DECISION_MAKING",
+  "safety_notice": "Summarize only verified aggregate research outputs. Do not generate patient-level content, clinical advice, causal conclusions, or unverified interpretations.",
+  "data_classification": "aggregate",
+  "authorized_purpose": null,
+  "authorization_verified": false,
+  "reporting_route": {
+    "study_design": null,
+    "base_reporting_guideline_and_version": null,
+    "applicable_extensions": [],
+    "protocol_reference": null,
+    "sap_reference": null,
+    "registry_reference": null
+  },
+  "sections": {
+    "scope_and_population": {"status": "missing", "source_fact_ids": []},
+    "methods": {"status": "missing", "source_fact_ids": []},
+    "analysis_set_and_estimand": {"status": "missing", "source_fact_ids": []},
+    "results": {"status": "missing", "source_fact_ids": []},
+    "missingness_and_exclusions": {"status": "missing", "source_fact_ids": []},
+    "safety_summary_if_applicable": {"status": "missing", "source_fact_ids": []},
+    "limitations": {"status": "missing", "source_fact_ids": []},
+    "interpretation_by_accountable_authors": {"status": "missing", "source_fact_ids": []},
+    "funding_and_conflicts": {"status": "missing", "source_fact_ids": []}
+  },
+  "provenance_manifest": null,
+  "review": {
+    "accountable_author_review": "pending",
+    "statistical_review": "pending",
+    "clinical_review": "pending",
+    "privacy_review": "pending",
+    "publication_authorized": false
+  }
+}

package/skills/clinical-reports/assets/terminology_manifest_template.json

@@ -0,0 +1,11 @@
+{
+  "schema_version": "2.0",
+  "artifact_kind": "terminology_manifest",
+  "manifest_status": "BLOCKED_INCOMPLETE",
+  "safety_notice": "Record only codes already selected and verified by qualified reviewers. Syntax or local-dictionary matching does not validate clinical meaning.",
+  "data_classification": null,
+  "authorized_purpose": null,
+  "authorization_verified": false,
+  "provenance_manifest": null,
+  "entries": []
+}

package/skills/clinical-reports/assets/trial_protocol_reporting_checklist.json

@@ -0,0 +1,70 @@
+{
+  "schema_version": "2.0",
+  "artifact_kind": "randomized_trial_protocol_reporting_manifest",
+  "draft_status": "BLOCKED_INCOMPLETE_REPORTING_CHECKLIST_NOT_A_PROTOCOL_OR_ETHICS_APPROVAL",
+  "safety_notice": "This manifest tracks SPIRIT reporting-item coverage only. It does not design, approve, register, conduct, amend, or submit a trial protocol.",
+  "data_classification": "aggregate",
+  "authorized_purpose": null,
+  "authorization_verified": false,
+  "guidance": {
+    "base": "SPIRIT 2025",
+    "item_count": 34,
+    "statement_and_explanation_checked": false,
+    "applicable_extensions": [],
+    "applicable_extensions_reviewed": false,
+    "extension_conflicts_resolved_by_methodologist": false
+  },
+  "protocol_metadata": {
+    "authorized_protocol_reference": null,
+    "protocol_version": null,
+    "registry_reference": null,
+    "ethics_record_reference": null
+  },
+  "checklist_items": {
+    "S01": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S02": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S03": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S04": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S05": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S06": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S07": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S08": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S09": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S10": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S11": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S12": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S13": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S14": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S15": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S16": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S17": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S18": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S19": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S20": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S21": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S22": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S23": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S24": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S25": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S26": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S27": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S28": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S29": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S30": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S31": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S32": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S33": {"status": "missing", "source_fact_ids": [], "official_item_locator": null},
+    "S34": {"status": "missing", "source_fact_ids": [], "official_item_locator": null}
+  },
+  "not_applicable_rationales": {},
+  "participant_timeline_source_fact_ids": [],
+  "provenance_manifest": null,
+  "review": {
+    "investigator_sponsor_review": "pending",
+    "methodologist_review": "pending",
+    "statistical_review": "pending",
+    "safety_review": "pending",
+    "ethics_regulatory_review": "pending",
+    "protocol_approved": false
+  }
+}

package/skills/clinical-reports/references/README.md

@@ -0,0 +1,34 @@
+# Clinical Reports References
+
+These references support local, deterministic drafting and review. They are not clinical, legal, regulatory, privacy, publication, or accreditation advice and do not establish compliance.
+
+## Safety boundary
+
+- Use only synthetic, de-identified, or aggregate data.
+- Populate drafts only from verified authorized source facts.
+- Do not diagnose, treat, dose, triage, interpret raw observations, fabricate results, sign, file, or submit.
+- Do not use external models, APIs, image tools, or cross-skill calls.
+- Keep every output marked as a draft requiring qualified review.
+
+## File map
+
+| File | Use |
+|---|---|
+| `report_type_routing.md` | Select the artifact and exact source family before drafting |
+| `case_report_guidelines.md` | CARE case-report structure, consent, and publication safeguards |
+| `diagnostic_reports_standards.md` | Radiology, pathology, and laboratory field boundaries |
+| `clinical_trial_reporting.md` | CONSORT 2025, SPIRIT 2025, ICH E3, and ICH E6(R3) |
+| `safety_reporting.md` | ICH E2 and FDA safety-reporting distinctions |
+| `privacy_and_deidentification.md` | HHS de-identification methods and process limits |
+| `medical_terminology.md` | Versioned terminology and syntax-versus-semantics limits |
+| `data_presentation.md` | Aggregate tables, denominators, units, dates, and missingness |
+| `professional_review.md` | Ethics, accountability, review, and sign-off |
+| `sources.md` | Dated official-source ledger |
+
+## Source handling
+
+`sources.md` records primary or official sources checked on 2026-07-23. Requirements, regional adoption, controlled terminologies, and professional standards can change. Before real-world use, a qualified reviewer must verify the current official source, applicable jurisdiction, institution, sponsor procedure, protocol, statistical analysis plan, and target-journal instructions.
+
+## Terminology
+
+“Required” in these references means required by the cited source within its stated scope, not universally required. “Complete” means structurally present in a manifest, not clinically correct. Script results never authorize use, release, signature, filing, or submission.

package/skills/clinical-reports/references/case_report_guidelines.md

@@ -0,0 +1,72 @@
+# CARE Case-Report Drafting
+
+## Current source
+
+The official CARE site continues to identify the **2013 CARE Checklist** as the core checklist. The 2017 explanation and elaboration supplies rationale and examples. CARE is reporting guidance for case reports; it does not authorize record access, establish consent, prove de-identification, or replace journal instructions.
+
+## Thirteen checklist headings
+
+Preserve the official structure:
+
+1. title;
+2. key words;
+3. abstract;
+4. introduction;
+5. patient information;
+6. clinical findings;
+7. timeline;
+8. diagnostic assessment;
+9. therapeutic intervention;
+10. follow-up and outcomes;
+11. discussion;
+12. patient perspective;
+13. informed consent.
+
+Use the official checklist and explanation for subitems. The local validator checks only that all headings have an allowed status and verified fact references; it does not judge clinical accuracy or CARE adherence.
+
+## Safe use
+
+- Begin with `assets/case_report_template.json`.
+- Use de-identified source facts, not copied charts or free-text records.
+- Keep direct identifiers and contact details out of the draft manifest.
+- Represent chronology with relative study/case offsets when authorized and scientifically adequate; do not alter chronology to disguise conflicts.
+- Preserve diagnostic and therapeutic statements as attributed facts from authorized records. Do not independently diagnose, rationalize treatment, or recommend care.
+- Attribute the patient perspective to an authorized source; never invent a quote.
+- Keep uncertainty, missing follow-up, adverse outcomes, and limitations visible.
+- Do not claim novelty until an accountable author has reviewed the literature.
+- Avoid causal or general treatment claims from a single case.
+
+## Consent and privacy
+
+CARE includes informed consent as an item, but a template cannot obtain or verify consent.
+
+- Record only a consent status verified by the responsible human reviewer.
+- Do not create a stock statement asserting that consent was obtained.
+- Consent for publication and HIPAA de-identification are separate questions.
+- De-identification does not necessarily remove all re-identification risk, particularly for rare conditions, small communities, images, unusual timelines, or distinctive combinations.
+- Journal, institution, law, ethics-board policy, and circumstances involving minors, deceased persons, or persons unable to consent require qualified review.
+
+## Fail-closed statuses
+
+Each CARE item uses one of:
+
+- `verified_present` — supported by one or more verified source-fact IDs;
+- `not_applicable_with_rationale` — a qualified reviewer supplied a recorded rationale;
+- `missing` — blocks structural readiness;
+- `conflict` — source records disagree and human resolution is required.
+
+The consent item cannot be waived by the script. A missing or unresolved consent status blocks publication handoff.
+
+## Qualified review
+
+Before any journal handoff, accountable authors and the appropriate clinical, privacy/legal, and institutional reviewers must verify:
+
+- source accuracy and chronology;
+- consent and authorization;
+- privacy and image/metadata handling;
+- terminology and clinical interpretation;
+- discussion claims and citations;
+- conflicts, limitations, and adverse outcomes;
+- the target journal’s current instructions.
+
+A structural result of `STRUCTURE_COMPLETE_REVIEW_REQUIRED` is not permission to submit.

package/skills/clinical-reports/references/clinical_trial_reporting.md

@@ -0,0 +1,97 @@
+# Clinical-Trial Reporting
+
+## Keep the artifacts distinct
+
+- **Protocol**: planned design and conduct. Route randomized-trial protocols to SPIRIT 2025.
+- **Results manuscript**: completed trial reporting for publication. Route randomized-trial results to CONSORT 2025.
+- **Clinical Study Report (CSR)**: integrated clinical and statistical report of an individual study. Route to ICH E3 and its Q&A.
+- **Safety report**: individual or aggregate safety communication. Route separately; see `safety_reporting.md`.
+
+One checklist does not substitute for another.
+
+## CONSORT 2025
+
+The official SPIRIT–CONSORT site describes CONSORT 2025 as a **30-item** minimum checklist plus a participant flow diagram for results of randomized trials. The primary statement was published 14 April 2025.
+
+Use the statement, expanded checklist, and explanation/elaboration together. Check the current extension catalogue for every applicable design, data, intervention, and population extension. In particular, consider the current harms extension for adverse-event reporting.
+
+The local template stores item IDs `C01`–`C30`; it does not reproduce, reinterpret, or score the checklist. A qualified methodologist must map each item to the official wording and resolve interactions with extensions.
+
+Do not:
+
+- fabricate a flow count or reason;
+- infer analysis populations, endpoints, estimands, missing-data methods, or harms;
+- add a figure when no verified data support it;
+- treat a reporting checklist as proof of valid conduct or analysis.
+
+## SPIRIT 2025
+
+SPIRIT 2025 is the current reporting guideline for randomized-trial protocols. It was published 28 April 2025, contains **34 minimum items** plus a participant timeline figure, and supersedes SPIRIT 2013.
+
+Notable updated areas include open science, harms assessment, intervention/comparator description, and patient/public involvement. Use the statement, expanded checklist, explanation/elaboration, and applicable extensions together.
+
+The local template stores item IDs `S01`–`S34`. It checks item coverage only. It does not create a protocol, design a trial, select endpoints, specify interventions or doses, perform ethics review, or authorize conduct.
+
+## ICH E3 Clinical Study Reports
+
+ICH E3 reached Step 4 on 30 November 1995. The current E3 Q&A (R1), dated 6 July 2012, states that E3 is guidance rather than a rigid required template and may be adapted with justified additions, deletions, renaming, or reordering.
+
+The structural validator expects these canonical sections:
+
+1. Title Page
+2. Synopsis
+3. Table of Contents for the Individual Clinical Study Report
+4. List of Abbreviations and Definitions of Terms
+5. Ethics
+6. Investigators and Study Administrative Structure
+7. Introduction
+8. Study Objectives
+9. Investigational Plan
+10. Study Patients
+11. Efficacy Evaluation
+12. Safety Evaluation
+13. Discussion and Overall Conclusions
+14. Tables, Figures, and Graphs Referred to but Not Included in the Text
+15. Reference List
+16. Appendices
+
+Use `not_applicable_with_rationale` only when the study design and a qualified regulatory reviewer support the adaptation. The validator does not assess scientific content, appendices, eCTD placement, regional acceptability, or submission readiness.
+
+## ICH E6(R3)
+
+ICH adopted E6(R3) Principles and Annex 1 on 6 January 2025, Annex 2 on 3 June 2026, and a consolidated final guideline on 16 June 2026.
+
+The guideline:
+
+- applies to interventional trials of investigational products intended for regulatory submission, while principles may be applicable more broadly under local requirements;
+- uses flexible, fit-for-purpose, proportionate, risk-based approaches;
+- emphasizes participant rights, safety, and well-being and reliable results;
+- requires attention to data governance, records, security, quality management, provenance, and traceability;
+- expects the sponsor to describe the trial quality-management approach in the CSR.
+
+Step 4 adoption does not prove regional implementation. A qualified regulatory professional must verify the applicable adopted version and transition rules.
+
+## Data integrity and provenance
+
+For every populated field:
+
+- retain the protocol/SAP-defined population and endpoint language;
+- identify the verified source and field path;
+- preserve prespecified versus post hoc status;
+- preserve database-cut and coding-dictionary versions;
+- report denominators and missingness explicitly;
+- record transformations and reconciliation decisions made by accountable humans;
+- expose unresolved discrepancies.
+
+Do not copy subject-level listings into local examples or tests. Use aggregate manifests and hashes.
+
+## Review owners
+
+- accountable clinical author: clinical interpretation;
+- trial statistician: analysis populations, estimands, methods, outputs, and denominators;
+- safety physician/professional: safety interpretation and individual-case decisions;
+- data management/quality: source lineage and reconciliation;
+- privacy/legal/ethics: authorization and disclosure;
+- regulatory professional: CSR structure, regional rules, and submission package.
+
+No script result replaces any of these reviews.

package/skills/clinical-reports/references/data_presentation.md

@@ -0,0 +1,92 @@
+# Aggregate Data Presentation
+
+Present verified outputs without changing their meaning. Do not calculate a clinical conclusion, select an analysis, or repair source discrepancies.
+
+## Mandatory table metadata
+
+Every table should identify:
+
+- artifact and analysis purpose;
+- data cut and source-output version;
+- analysis population/set;
+- treatment/group labels;
+- denominator for every group and row when it varies;
+- whether a value is a subject count, event count, observation count, or estimate;
+- units, time point/window, and summary statistic;
+- missing, unknown, not assessed, suppressed, or not applicable values;
+- coding dictionary/version/language where applicable;
+- statistical method and multiplicity status only when copied from a verified output;
+- provenance manifest and reviewer status.
+
+## Counts and denominators
+
+- Show `n/N (%)`, not a percentage alone, unless the governing output specifies another form.
+- Require `0 <= n <= N` and `N > 0`.
+- Recalculate only for consistency checking; do not silently replace the reported percentage.
+- State the rounding rule and tolerance.
+- Do not add subgroup percentages when the subgroup denominator is unknown.
+- Do not infer that denominators are randomized, treated, evaluable, or safety populations.
+- Keep event counts distinct from subjects affected; event counts can exceed the number of subjects.
+- Do not sum non-mutually-exclusive categories.
+
+## Dates and time
+
+- Use ISO 8601 in structured manifests.
+- Preserve source timezone and precision.
+- Distinguish event date, collection date, database cut, report date, and verification date.
+- Flag start-after-end and conflicting dates.
+- Do not impute a missing day, month, timezone, or chronology.
+- For de-identified case reports, use an authorized relative timeline; do not distort intervals.
+
+## Units and precision
+
+- Preserve source units.
+- Require a unit for every dimensional quantity.
+- Use one verified unit per comparable series or expose the mismatch.
+- Do not convert or normalize without an authorized traceable conversion rule.
+- Preserve clinically meaningful precision; do not create extra significant digits.
+- Identify SD, SE, CI, IQR, range, and denominator explicitly.
+
+## Missing and suppressed values
+
+Keep these states distinct:
+
+- `missing`;
+- `not_collected`;
+- `not_assessed`;
+- `unknown`;
+- `not_applicable`;
+- `suppressed_for_privacy`;
+- `zero`.
+
+Never convert a blank to zero. State small-cell suppression rules and ensure totals or complementary cells do not reveal suppressed values.
+
+## Adverse-event tables
+
+For term-level aggregate tables:
+
+- state MedDRA version and language;
+- state analysis set and denominator;
+- state counting rule from the verified SAP/output;
+- show subjects affected and event count separately;
+- do not add p-values or causal labels;
+- do not interpret between-group differences;
+- preserve threshold rules exactly;
+- have safety and statistical reviewers verify deduplication, hierarchy, and population.
+
+## Figures
+
+No figure is mandatory. Create one only when requested, supported by verified aggregate data, allowed by the target guidance, and reviewable without external image generation.
+
+A CONSORT flow diagram is part of CONSORT 2025 reporting, but every count and reason must come from verified trial outputs. A missing count remains missing; do not create a decorative or inferred diagram.
+
+## Deterministic consistency check
+
+`consistency_checker.py` can inspect:
+
+- ISO date and range ordering;
+- unit-label consistency;
+- `n/N (%)` arithmetic;
+- component-total arithmetic.
+
+It reports mismatches and review needs. It does not change the input, choose the correct source, or validate clinical/statistical meaning.

package/skills/clinical-reports/references/diagnostic_reports_standards.md

@@ -0,0 +1,76 @@
+# Diagnostic-Report Scaffolds
+
+These assets are structured field maps for authorized clinical services. They do not interpret data or produce a report suitable for patient care.
+
+## Radiology
+
+The ACR **Practice Parameter for Communication of Diagnostic Imaging Findings**, revised 2025 (Resolution 9), addresses diagnostic imaging reports, final-report principles, preliminary reports, nonroutine communication, informal communication, and organizational communication policies.
+
+Use `assets/radiology_report_template.json` only to map verified facts such as:
+
+- examination identity and status;
+- clinical indication as supplied;
+- technique and documented limitations;
+- comparison-source references;
+- findings and impression authored by the qualified interpreting professional;
+- nonroutine-communication record references;
+- amendments/corrections and report version.
+
+Do not:
+
+- inspect or interpret images;
+- generate normal findings, pertinent negatives, differential diagnoses, urgency, follow-up, or management recommendations;
+- select BI-RADS, LI-RADS, Lung-RADS, PI-RADS, or another category;
+- infer that a preliminary report is final;
+- initiate, simulate, or document a communication that did not occur.
+
+The responsible radiologist and organization control report content, communication, correction, and signature.
+
+## Pathology
+
+CAP publishes and updates organ- and specimen-specific Cancer Protocols. The CAP template page showed protocol updates on 17 June 2026 and a Breast DCIS correction on 24 June 2026 when checked. Protocol versions and required/core or conditional elements can change.
+
+Use `assets/pathology_report_template.json` only after a qualified pathologist selects:
+
+- exact organ/site and specimen/procedure;
+- current CAP protocol title and version, if applicable;
+- applicable biomarker protocol and staging edition;
+- local laboratory/reporting requirements.
+
+For CAP synoptic reporting within its scope, core and conditionally required data elements are represented as data-element/response pairs; applicability depends on the exact current protocol.
+
+Do not:
+
+- generate a gross or microscopic observation;
+- determine diagnosis, grade, stage, margin status, biomarker interpretation, or adequacy;
+- apply a generic cancer checklist in place of the current exact protocol;
+- convert `cannot be determined` or `not applicable` into a definitive value;
+- create a signature or final diagnosis.
+
+## Laboratory
+
+For applicable US nonwaived testing, 42 CFR 493.1291 addresses accurate and timely transmission, required report information, referral-laboratory handling, accessibility, and corrected reports. The exact regulation and laboratory policy control.
+
+Use `assets/lab_report_template.json` only to map results already released by the performing laboratory or verified source system. Preserve:
+
+- report status and version;
+- performing laboratory/source-system reference;
+- specimen and test identifiers held in the authorized system, not copied into examples;
+- result, units, reference interval, flags, method, and comments exactly as released;
+- correction link to both original and corrected reports;
+- documented notification reference when one exists.
+
+Do not:
+
+- calculate, normalize, convert, interpret, flag, or suppress a patient result;
+- supply a reference interval or “critical” threshold;
+- infer specimen adequacy;
+- recommend follow-up or treatment;
+- alter a referral laboratory’s result or interpretation;
+- release or sign a report.
+
+## Privacy and record integrity
+
+Operational diagnostic reports often require identifiers for positive patient matching. This skill does not process those production records. It accepts only synthetic, de-identified, or aggregate manifests. Use institution-controlled systems for real clinical records and follow applicable access, retention, correction, audit, and disclosure procedures.
+
+Every draft scaffold must remain `DRAFT_NOT_FOR_CLINICAL_USE` until the responsible licensed service reviews and completes it in its authorized system.

package/skills/clinical-reports/references/medical_terminology.md

@@ -0,0 +1,84 @@
+# Versioned Terminology and Schema Checks
+
+Terminology selection and coding are clinical/regulatory tasks. The local checker validates manifest shape and code syntax; it does not confirm that a code exists, is current, matches a display, or is clinically appropriate.
+
+## Required manifest fields
+
+For every coded item record:
+
+- `system`: controlled system name;
+- `system_uri`: canonical identifier supplied by the implementing organization;
+- `code`;
+- `display`;
+- `version`;
+- `language`;
+- `source_fact_id`;
+- `coding_status`: `verified_by_qualified_reviewer` or `unverified`;
+- `verified_by_role` and `verified_at` when verified.
+
+Do not infer a code from narrative text.
+
+## MedDRA
+
+- ICH developed MedDRA for regulatory information about human medical products.
+- MedDRA 29.0 was released in March 2026, with a transition date of 4 May 2026.
+- MedDRA uses a multiaxial hierarchy and version-specific currency/relationships.
+- State exact version and language.
+- Use the study/sponsor-authorized version, official licensed files, and current Points to Consider.
+- Do not assume the newest release is the required release.
+
+The aggregate adverse-event formatter accepts SOC and PT labels as supplied and does not validate hierarchy, codes, or coding quality.
+
+## LOINC
+
+LOINC identifies health observations, measurements, and documents. LOINC 2.82 was released 24 February 2026 and was current when checked.
+
+- A valid-looking `number-checkdigit` string is only syntactic evidence.
+- The method, property, timing, system/specimen, scale, and version can affect meaning.
+- Verify against the official release or authorized terminology service.
+- Review the LOINC license and third-party content terms.
+
+## SNOMED CT
+
+SNOMED CT concept identifiers are not clinically validated by their numeric shape.
+
+- Use the applicable international edition, national extension, and effective date.
+- Verify concept activity, module, description, and reference-set membership.
+- Comply with SNOMED International and national licensing/distribution requirements.
+- Do not embed or redistribute licensed terminology content through these assets.
+
+## ICD-10-CM
+
+ICD-10-CM changes by fiscal-year release and may require encounter, laterality, or placeholder characters.
+
+- Record the exact release and applicable jurisdiction.
+- Verify with official CDC/CMS files and coding guidance.
+- A regex match cannot establish billability, specificity, sequencing, or clinical correctness.
+- This skill does not support billing or reimbursement decisions.
+
+## UCUM and units
+
+Record the original unit exactly and, when an organization uses UCUM, record the verified UCUM expression separately. Do not automatically convert units in a report draft.
+
+Any conversion must have:
+
+- an authorized rule and version;
+- original value/unit;
+- converted value/unit;
+- precision/rounding rule;
+- source-fact and reviewer traceability.
+
+The consistency checker flags missing or inconsistent unit labels but performs no clinical conversion.
+
+## Optional local dictionary
+
+`terminology_validator.py --dictionary <file.json>` can compare code/display/version tuples with a caller-supplied local dictionary. The dictionary must be an authorized bounded JSON file.
+
+A match means only “matched this supplied dictionary.” It does not prove:
+
+- the dictionary is official, complete, current, or licensed for the use;
+- the chosen code is appropriate;
+- the clinical statement is true;
+- the report is compliant or ready for release.
+
+Without a dictionary, the strongest result is `SCHEMA_VALID_SYNTAX_ONLY_REVIEW_REQUIRED`.