@pikaa-ai/pikaa 0.2.5 → 0.3.0

package/skills/clinical-decision-support/references/safety_and_scope.md

@@ -0,0 +1,103 @@
+# Safety and Scope
+
+## Intended Use
+
+Use this skill only to create or check research, evaluation, documentation, and governance artifacts from synthetic or aggregate data.
+
+Acceptable examples:
+
+- an intended-use statement for a retrospective model evaluation;
+- an aggregate subgroup performance report;
+- a statistical analysis plan;
+- a GRADE evidence-profile shell for a human panel;
+- a release-gate traceability matrix;
+- a de-identification process checklist.
+
+## Prohibited Use
+
+Do not:
+
+- accept or produce a record about a person;
+- infer a diagnosis, prognosis, phenotype, biomarker class, or eligibility for a person;
+- recommend or compare care options for a person;
+- provide medication, dose, schedule, monitoring, or contraindication instructions;
+- triage, assign urgency, create an alarm, or suggest escalation;
+- deploy logic in an EHR, bedside tool, portal, order set, or alerting workflow;
+- represent output as clinical advice, a validated medical device, or an authorized clinical system;
+- claim legal, regulatory, quality-system, or HIPAA compliance.
+
+No disclaimer makes an otherwise prohibited workflow acceptable.
+
+## Stop Conditions
+
+Stop and do not process the input when any of the following is present:
+
+- names, record numbers, contact details, precise locations, or person-linked dates;
+- row-level records, timelines, notes, images, signals, or sequences;
+- a request about “this patient,” “this result,” or an individual case;
+- instructions to choose a therapy, test, dose, disposition, or urgency;
+- instructions to push output to a live clinical system;
+- an assertion that passing a checklist proves authorization or compliance.
+
+Explain the boundary briefly. For care, direct the requester to a licensed healthcare professional and locally validated, appropriately authorized systems. For privacy, regulatory, or legal determinations, direct them to qualified organizational reviewers.
+
+## Required Intended-Use Elements
+
+An artifact is incomplete unless it states:
+
+1. **Purpose** — the specific research or governance question.
+2. **Users** — named roles, not “clinicians” broadly.
+3. **Population scope** — aggregate cohort or synthetic data only.
+4. **Decision role** — descriptive, evaluative, or governance support.
+5. **Excluded uses** — every prohibited use above.
+6. **Data level** — aggregate or synthetic, with no PHI/raw rows supplied.
+7. **Limitations** — known gaps, assumptions, transportability, and failure modes.
+8. **Human review** — required roles and approval status.
+9. **Versioning** — owner, version, release date, changes, and retirement criteria.
+10. **Monitoring** — drift, calibration, subgroup performance, incidents, and review cadence when applicable.
+
+## Human Review Matrix
+
+| Artifact | Minimum review roles |
+|---|---|
+| Evidence profile | systematic-review methodologist; domain experts; panel chair |
+| Cohort report | statistician/epidemiologist; data steward; domain expert |
+| Survival plan | statistician with time-to-event expertise; domain expert |
+| Model/biomarker evaluation | prediction-model methodologist; assay/domain expert; fairness reviewer |
+| Privacy checklist | privacy official or qualified de-identification expert |
+| Logic traceability | system owner; independent validator; governance approver |
+| Regulatory context | qualified legal/regulatory counsel |
+
+Review completion must be recorded by the responsible organization. The scripts do not authenticate reviewers or approvals.
+
+## Safe Language
+
+Prefer:
+
+- “The aggregate evaluation estimated…”
+- “Performance differed across evaluated subgroups; causes and practical importance require review.”
+- “The evidence panel judged certainty as…; rationale and sources are recorded.”
+- “This checklist is complete; it is not a compliance determination.”
+- “External validation has not been performed.”
+
+Avoid:
+
+- “The model is safe/fair/clinically valid.”
+- “This biomarker means the patient should…”
+- “The tool is FDA compliant/approved.”
+- “The dataset is HIPAA compliant.”
+- “The recommendation is Grade 1A” without the framework, panel process, outcome-specific judgments, and source trail.
+
+## Audit Trail
+
+Record:
+
+- immutable artifact ID and version;
+- source versions and access dates;
+- data provenance and cut date;
+- code version and command;
+- declared thresholds before analysis;
+- reviewer roles, dates, decisions, and unresolved objections;
+- change reason, validation evidence, rollback plan, and retirement decision.
+
+Do not put secrets, credentials, or patient information in audit logs.

package/skills/clinical-decision-support/references/security_validation.md

@@ -0,0 +1,60 @@
+# Security Validation Record
+
+Validation date: **2026-07-23** (local project date).
+
+## Baseline
+
+The repository `SECURITY.md` section recorded 11 findings:
+
+- 3 CRITICAL findings for cross-file environment-variable/network exfiltration behavior;
+- 1 HIGH finding for transmitting a credential to an external service;
+- 5 MEDIUM findings for command chaining, credential flow, undeclared network use, and environment harvesting;
+- 2 LOW findings for mandatory cross-skill invocation and dependency concerns.
+
+The affected external schematic wrappers were the now-deleted files
+`generate_schematic.py` and `generate_schematic_ai.py`.
+
+## Remediation
+
+- Deleted both schematic-generation scripts.
+- Removed all external service, LLM, image, credential, and environment-variable behavior.
+- Removed mandatory figures and cross-skill calls.
+- Replaced unsafe person-level classification and care-pathway helpers with aggregate or planning-only tools.
+- Added bounded local JSON handling, person-level-key rejection, output limits, and deterministic schemas.
+- Added static AST tests that reject network libraries, dynamic code execution, credential access, and executable serialization.
+
+## Post-Refresh Results
+
+- Direct behavioral scan: **SAFE, 0 findings**.
+- Pull-request gate with `--fail-on HIGH`: **passed** with 0 CRITICAL and
+  0 HIGH. Repeated LLM-assisted runs returned 2–3 LOW findings because the
+  analyzer is nondeterministic.
+
+## Accepted LOW Findings
+
+Across repeated runs, the nondeterministic analyzer reported different subsets of
+these LOW observations:
+
+1. **Optional `allowed-tools` field absent** — accepted as informational. The
+   Agent Skills specification does not require it; compatibility and runtime
+   instructions explicitly prohibit network and credential access.
+2. **Broad description** — accepted. The scope intentionally covers the related research-evaluation artifacts requested for this safety refresh, while the frontmatter and first body section explicitly exclude care and live operation.
+3. **Person-level key filtering uses a denylist** — accepted as a documented limitation, not a privacy guarantee. Input is contractually restricted to synthetic or aggregate schemas, common person-level fields are rejected as defense in depth, and the documentation repeatedly requires qualified privacy review. The filter cannot detect every identifier name or sensitive value and is never presented as de-identification.
+4. **Occasional missing-file report** — accepted as an analyzer false
+   positive. Some runs invented a `templates/` directory and nonexistent
+   `assets/*.md` references. The deterministic
+   `test_documented_local_paths_exist` check resolves every documented local
+   path and passes.
+
+None of the accepted findings permits network access, sensitive-data handling, or clinical action.
+
+## Reproduction
+
+```bash
+uv run skill-scanner scan skills/clinical-decision-support --use-behavioral
+
+uv run python scan_pr_skills.py \
+  --fail-on HIGH \
+  --output /tmp/clinical-decision-support-pr-scan.md \
+  skills/clinical-decision-support
+```

package/skills/clinical-decision-support/references/sources.md

@@ -0,0 +1,119 @@
+# Authoritative Source Ledger
+
+Research cutoff and link check: **2026-07-23**.
+
+Research used `parallel-cli search` and `parallel-cli extract`, constrained to official agencies, standards groups, guideline hosts, and primary publications. Status labels below reflect the source on the cutoff date. A link in this ledger is not an endorsement of an artifact or a substitute for checking the current source before use.
+
+## FDA: CDS and AI-Enabled Devices
+
+- **Clinical Decision Support Software** — FDA final guidance, January 2026; page reissued/content current January 29, 2026. Defines FDA's current interpretation of non-device CDS criteria and device-software boundaries.
+  https://www.fda.gov/regulatory-information/search-fda-guidance-documents/clinical-decision-support-software
+- **Marketing Submission Recommendations for a Predetermined Change Control Plan for AI-Enabled Device Software Functions** — FDA final guidance, August 2025. Used for planned modifications, validation methodology, impact assessment, and change-control concepts.
+  https://www.fda.gov/regulatory-information/search-fda-guidance-documents/marketing-submission-recommendations-predetermined-change-control-plan-artificial-intelligence
+- **AI-Enabled Device Software Functions: Lifecycle Management and Marketing Submission Recommendations** — FDA draft guidance, January 2025; explicitly draft/not for implementation on the cutoff date. Used only as clearly labeled draft lifecycle context.
+  https://www.fda.gov/regulatory-information/search-fda-guidance-documents/artificial-intelligence-enabled-device-software-functions-lifecycle-management-and-marketing
+- **Good Machine Learning Practice for Medical Device Development: Guiding Principles** — FDA page current December 19, 2025, linking the January 2025 IMDRF final principles. Used for lifecycle, representative data, human-AI team, and independent testing themes.
+  https://www.fda.gov/medical-devices/software-medical-device-samd/good-machine-learning-practice-medical-device-development-guiding-principles
+- **Transparency for Machine Learning-Enabled Medical Devices: Guiding Principles** — FDA/Health Canada/MHRA, June 13, 2024. Used for intended users, limitations, data characterization, uncertainty, human factors, monitoring, and update communication.
+  https://www.fda.gov/medical-devices/software-medical-device-samd/transparency-machine-learning-enabled-medical-devices-guiding-principles
+- **Artificial Intelligence in Software as a Medical Device** — FDA topic page, content current March 25, 2025 in search results. Used to cross-check the guidance sequence.
+  https://www.fda.gov/medical-devices/software-medical-device-samd/artificial-intelligence-software-medical-device
+
+## ONC / HTI-1
+
+- **HTI-1 Final Rule** — official Federal Register text, January 2024. Used for the legal scope of predictive DSI/source-attribute and intervention-risk-management requirements.
+  https://www.federalregister.gov/citation/89-FR-1391
+- **HTI-1 Decision Support Interventions Fact Sheet** — ONC, December 2023. Used for the section 170.315(b)(11) overview and predictive-DSI transparency categories.
+  https://www.healthit.gov/wp-content/uploads/2023/12/HTI-1_DSI_fact-sheet_508.pdf
+- **Requirements for Decision Support Interventions and Predictive Models** — ONC final-rule presentation, January 18, 2024. Used for intended use, population, user, decision role, out-of-scope use, fairness, validation, performance, and maintenance source attributes.
+  https://healthit.gov/wp-content/uploads/2024/01/DSI_HTI1-Final-Rule-Presentation_508.pdf
+- **HTI-1 Final Rule landing page** — ONC. Used to verify official supporting materials and current resource location.
+  https://healthit.gov/regulations/hti-rules/hti-1-final-rule
+
+## GRADE
+
+- **GRADE Working Group** — official overview and minimum requirements. Used for outcome-specific certainty, explicit domain judgments, evidence profiles, and Evidence-to-Decision separation.
+  https://www.gradeworkinggroup.org/
+- **GRADE Book** — official current resource, progressively replacing the prior handbook by 2026. Used as the preferred methodology entry point.
+  https://book.gradepro.org/
+- **GRADE Handbook** — legacy/current transition resource. Retained for comparison where a GRADE Book chapter is not yet available; verify against the GRADE Book.
+  https://gradepro.org/handbook
+
+## AI and Clinical-Study Reporting
+
+- **TRIPOD+AI** — Collins et al., BMJ 2024;385:e078378, published April 16, 2024. Reporting of prediction-model development/evaluation using regression or machine learning.
+  https://www.bmj.com/content/385/bmj-2023-078378
+- **TRIPOD+AI EQUATOR record** — scope, checklist, and related materials.
+  https://www.equator-network.org/reporting-guidelines/tripod-statement
+- **CONSORT-AI** — Liu et al., Nature Medicine 2020;26:1364-1374, published September 9, 2020. AI-intervention randomized-trial reports.
+  https://www.nature.com/articles/s41591-020-1034-x
+- **CONSORT 2025** — Hopewell et al., BMJ 2025;389:e081123, published April 14, 2025. Current generic base statement used with CONSORT-AI.
+  https://www.bmj.com/content/389/bmj-2024-081123
+- **SPIRIT-AI** — Rivera et al., Nature Medicine 2020;26:1351-1363, published September 9, 2020. AI-intervention trial protocols.
+  https://www.nature.com/articles/s41591-020-1037-7
+- **SPIRIT 2025** — current generic base statement used with SPIRIT-AI.
+  https://pubmed.ncbi.nlm.nih.gov/40295741
+- **DECIDE-AI** — Vasey et al., Nature Medicine 2022;28:924-933, published May 18, 2022. Early-stage live clinical evaluation of AI-based decision-support systems. Included for reporting context; live evaluation is outside this skill.
+  https://www.nature.com/articles/s41591-022-01772-9
+- **DECIDE-AI EQUATOR record** — scope and publication links.
+  https://www.equator-network.org/reporting-guidelines/reporting-guideline-for-the-early-stage-clinical-evaluation-of-decision-support-systems-driven-by-artificial-intelligence-decide-ai/
+- **STARD-AI** — Sounderajah et al., Nature Medicine, published September 15, 2025, DOI 10.1038/s41591-025-03953-8. Final reporting guideline for AI diagnostic-accuracy studies.
+  https://www.nature.com/articles/s41591-025-03953-8
+- **STARD-AI EQUATOR record** — final status, scope, citation, and checklist location.
+  https://www.equator-network.org/reporting-guidelines/the-stard-ai-reporting-guideline-for-diagnostic-accuracy-studies-using-artificial-intelligence/
+
+## Prediction-Model Risk of Bias
+
+- **PROBAST+AI** — Moons et al., BMJ 2025;388:e082505, published March 24, 2025. Current quality/risk-of-bias/applicability tool for regression and AI prediction models; separates development from evaluation and uses participants/data sources, predictors, outcome, and analysis domains.
+  https://pubmed.ncbi.nlm.nih.gov/40127903
+- **PROBAST+AI project site** — tool resources and updates.
+  https://www.probast.org/probast_ai
+
+## Privacy and De-identification
+
+- **HHS Guidance Regarding Methods for De-identification of PHI** — official OCR guidance; page current March 20, 2026 in extraction. Used for Expert Determination, Safe Harbor, actual knowledge, derivatives, and free-text cautions.
+  https://www.hhs.gov/hipaa/for-professionals/special-topics/de-identification/index.html
+- **45 CFR 164.514** — current eCFR text for de-identification and related requirements.
+  https://www.ecfr.gov/current/title-45/subtitle-A/subchapter-C/part-164/subpart-E/section-164.514
+
+## ICH
+
+- **ICH E6(R3) consolidated Step 4 guideline** — final version adopted June 16, 2026, consolidating principles, Annex 1, and Annex 2. Used for quality by design, fit-for-purpose data, oversight, privacy, auditability, and modern trial settings.
+  https://database.ich.org/sites/default/files/ICH%20E6(R3)_Step4_FinalConsolidatedGuideline_2026_0616_.pdf
+- **ICH E9(R1) Addendum on Estimands and Sensitivity Analysis** — final, adopted November 20, 2019. Used for estimand-led planning and sensitivity analysis.
+  https://database.ich.org/sites/default/files/E9-R1_Step4_Guideline_2019_1203.pdf
+- **ICH efficacy-guideline index** — official status/version cross-check.
+  https://www.ich.org/page/efficacy-guidelines
+
+## Cohort, Survival, and Biomarker Methods
+
+- **STROBE** — official reporting guidance for observational studies.
+  https://www.strobe-statement.org/
+- **RECORD** — reporting extension for routinely collected health data.
+  https://www.record-statement.org/
+- **REMARK** — reporting recommendations for tumor-marker prognostic studies.
+  https://www.equator-network.org/reporting-guidelines/reporting-recommendations-for-tumour-marker-prognostic-studies-remark
+- **FDA-NIH BEST Resource** — living biomarker and endpoint terminology resource, 2016 onward.
+  https://www.ncbi.nlm.nih.gov/books/NBK326791/
+- **External validation of clinical prediction models** — Riley et al., BMJ 2024;384:e074820, published January 15, 2024. Used for locked-model evaluation, calibration, discrimination, utility, and transparent reporting.
+  https://www.bmj.com/content/384/bmj-2023-074820
+- **External-validation sample size** — Riley et al., Statistics in Medicine 2021. Used to reject blanket event-count rules and emphasize precision targets.
+  https://pmc.ncbi.nlm.nih.gov/articles/PMC8352630
+- **Calibration: the Achilles heel of predictive analytics** — Van Calster et al., BMC Medicine 2019. Used for calibration assessment and interpretation.
+  https://pubmed.ncbi.nlm.nih.gov/31842878
+- **Restricted mean survival time** — Royston and Parmar, BMC Medical Research Methodology 2013;13:152. Used as an alternative population-level summary when proportional hazards is doubtful.
+  https://pubmed.ncbi.nlm.nih.gov/24314264/
+- **Competing risks introduction** — Austin, Lee, and Fine, Circulation 2016;133:601-609. Used to distinguish cause-specific hazards, subdistribution hazards, and cumulative incidence.
+  https://pubmed.ncbi.nlm.nih.gov/26858290/
+- **Fine-Gray reporting recommendations** — Austin and Fine, Statistics in Medicine 2017;36:4391-4400. Used for careful interpretation of subdistribution hazard models.
+  https://pmc.ncbi.nlm.nih.gov/articles/PMC5698744
+
+## Deliberately Out of Scope
+
+HL7 CDS Hooks, SMART on FHIR, and FHIR implementation guidance were not
+added because the version 2.0 safety redesign deliberately removes
+recommendation-oriented and live CDS behavior. It produces offline
+research/governance artifacts only; implementation guidance would conflict
+with the hard boundary.
+
+No source requiring an API key, external model, image generator, or network call is used at runtime.

package/skills/clinical-decision-support/references/study_reporting.md

@@ -0,0 +1,134 @@
+# Study Reporting and Appraisal
+
+Checked 2026-07-23.
+
+## First Principle
+
+Choose by study purpose, design, and evaluation stage. A reporting guideline states what to report; it does not prove that the study was well designed, unbiased, clinically useful, safe, or effective.
+
+Use risk-of-bias/applicability tools separately and preserve human judgments.
+
+## Selection Map
+
+| Study or artifact | Primary framework | Important companion |
+|---|---|---|
+| Observational cohort/case-control/cross-sectional | STROBE | RECORD for routinely collected data |
+| Prediction model development or evaluation | TRIPOD+AI | PROBAST+AI |
+| Tumor prognostic marker | REMARK | Appropriate risk-of-bias and assay guidance |
+| Diagnostic accuracy | STARD | STARD-AI when the index test uses AI |
+| Randomized AI intervention protocol | Current SPIRIT base | SPIRIT-AI extension |
+| Randomized AI intervention report | Current CONSORT base | CONSORT-AI extension |
+| Early-stage live AI support evaluation | DECIDE-AI | Design-specific guideline |
+| Evidence profile | GRADE | Design-specific risk-of-bias tools |
+
+## Observational Data
+
+### STROBE
+
+STROBE addresses reporting of cohort, case-control, and cross-sectional studies. Use the design-specific checklist and explanation material from the [STROBE site](https://www.strobe-statement.org/).
+
+### RECORD
+
+RECORD extends STROBE for routinely collected health data such as administrative, EHR, primary-care surveillance, and registry data. It emphasizes code lists/algorithms, database linkage, selection, cleaning, and data-access transparency. See the [RECORD site](https://www.record-statement.org/).
+
+Neither framework authorizes this skill to read EHR rows.
+
+## Prediction Models
+
+### TRIPOD+AI
+
+[TRIPOD+AI](https://www.bmj.com/content/385/bmj-2023-078378), published April 16, 2024, updates reporting guidance for development and evaluation of clinical prediction models using regression or machine-learning methods. It primarily targets non-generative models.
+
+Report, at minimum:
+
+- intended use, target population, outcome, horizon, and setting;
+- data sources, eligibility, sampling, and preprocessing;
+- predictor/outcome definitions and timing;
+- missing data;
+- sample-size rationale;
+- full model specification or access;
+- internal-validation method;
+- discrimination and calibration with uncertainty;
+- external validation and transportability;
+- subgroup performance and fairness considerations;
+- intended user, presentation, and limitations.
+
+### PROBAST+AI
+
+[PROBAST+AI](https://pubmed.ncbi.nlm.nih.gov/40127903), published March 24, 2025, replaces the original PROBAST for broad prediction-model assessment. It has two distinct parts:
+
+- **model development** — quality and applicability;
+- **model evaluation** — risk of bias and applicability.
+
+Both parts use four domains:
+
+1. participants and data sources;
+2. predictors;
+3. outcome;
+4. analysis.
+
+Applicability is assessed for participants/data sources, predictors, and outcome. Do not average signaling questions into a score. Domain and overall judgments require knowledgeable assessors and rationale.
+
+## Biomarker Studies
+
+Use the FDA-NIH [BEST Resource](https://www.ncbi.nlm.nih.gov/books/NBK326791/) for terminology. Distinguish:
+
+- diagnostic;
+- monitoring;
+- pharmacodynamic/response;
+- predictive;
+- prognostic;
+- safety;
+- susceptibility/risk;
+- surrogate endpoint biomarkers.
+
+A biomarker is not itself a measure of how a person feels, functions, or survives. Analytical validation, clinical validation, and clinical utility are distinct.
+
+For tumor prognostic markers, use [REMARK](https://www.equator-network.org/reporting-guidelines/reporting-recommendations-for-tumour-marker-prognostic-studies-remark). Report specimen handling, assay methods, prespecified hypotheses/cut points, participant flow, missing data, analysis, effect estimates, and validation.
+
+## AI Diagnostic Accuracy
+
+[STARD-AI](https://www.nature.com/articles/s41591-025-03953-8) was published September 15, 2025. It adds AI-specific or modified items to STARD 2015 for diagnostic-accuracy studies, including:
+
+- dataset practices;
+- AI index-test description and evaluation;
+- algorithmic bias and fairness;
+- applicability and generalizability;
+- transparent participant flow and reference-standard handling.
+
+Use STARD-AI with STARD. Do not use it for a prognostic prediction model merely because the model returns a class.
+
+## AI Trial Protocols and Reports
+
+[SPIRIT-AI](https://www.nature.com/articles/s41591-020-1037-7) and [CONSORT-AI](https://www.nature.com/articles/s41591-020-1034-x) were published September 9, 2020.
+
+- Use SPIRIT-AI for protocols evaluating an AI intervention.
+- Use CONSORT-AI for reports of randomized trials evaluating an AI intervention.
+- Apply them with the current generic [SPIRIT 2025](https://pubmed.ncbi.nlm.nih.gov/40295741) or [CONSORT 2025](https://www.bmj.com/content/389/bmj-2024-081123) statement, respectively.
+
+AI extensions emphasize the intervention version, input acquisition/quality handling, human-AI interaction, integration requirements, errors/failures, and analysis of performance.
+
+## Early Live Evaluation
+
+[DECIDE-AI](https://www.nature.com/articles/s41591-022-01772-9), published May 18, 2022, covers early-stage live clinical evaluation of AI-based decision-support systems and includes human factors, workflow, safety, and iterative change reporting.
+
+Live evaluation affects real care and is outside this skill's execution boundary. Use the guideline only to understand documentation requirements. Such work requires an approved protocol, qualified investigators, safety oversight, validated systems, applicable authorization, and institutional governance.
+
+## Cross-Cutting Reporting
+
+Always disclose:
+
+- prespecified versus exploratory work;
+- all evaluated outcomes and analyses, including negative results;
+- effect sizes and uncertainty;
+- missingness and exclusions;
+- conflicts, funding, and developer involvement;
+- version and data cut dates;
+- external validation;
+- subgroup representation and performance;
+- calibration and decision thresholds;
+- human-factors methods;
+- incidents, failures, drift, updates, and monitoring;
+- access to protocol, analysis plan, code, model, and data when lawful and feasible.
+
+Never state “reported according to” as proof of adherence without a completed checklist and human verification.

package/skills/clinical-decision-support/references/survival_analysis.md

@@ -0,0 +1,156 @@
+# Survival-Analysis Planning
+
+## Scope
+
+The bundled script validates a plan. It does not read time-to-event rows, fit models, draw curves, or provide an individual prognosis.
+
+## Start With the Estimand
+
+Align:
+
+1. **Population** — eligibility and analysis set.
+2. **Condition/comparison** — intervention, exposure, or groups being contrasted.
+3. **Variable/endpoint** — event definition and ascertainment.
+4. **Intercurrent-event strategy** — how events such as discontinuation, rescue therapy, switching, or competing events relate to the question.
+5. **Population-level summary** — risk, survival probability, restricted mean survival time, hazard contrast, quantile, or another justified measure.
+6. **Time horizon** — clinically and statistically justified.
+
+Record time zero, delayed entry, time scale, follow-up end, and calendar/data-cut date.
+
+## Endpoint Definition
+
+Specify:
+
+- exact event;
+- competing events;
+- recurrent events if relevant;
+- ascertainment schedule and adjudication;
+- censoring rules;
+- handling of same-day and tied events;
+- loss to follow-up;
+- administrative censoring;
+- endpoint changes and versioning.
+
+Do not treat a competing event as ordinary independent censoring when the target is absolute event probability.
+
+## Descriptive Estimation
+
+Kaplan-Meier estimates are suitable for survival from the event of interest under appropriate censoring assumptions. Report:
+
+- numbers at risk;
+- events and censoring;
+- estimates at prespecified times with intervals;
+- median only if estimable;
+- follow-up distribution using an appropriate method;
+- truncation where risk sets become uninformative.
+
+When competing events exist, use cumulative-incidence methods for event probabilities. Naively censoring competing events in Kaplan-Meier can overestimate absolute incidence.
+
+## Group Comparisons
+
+The log-rank test compares event-time distributions and is most powerful under proportional alternatives. It does not quantify an effect. Pre-specify alternatives if curves may cross or effects may be delayed.
+
+A Cox model estimates a hazard contrast conditional on model specification. Before presenting a single hazard ratio:
+
+- assess proportional hazards graphically and analytically;
+- examine functional forms;
+- evaluate influential observations and interactions;
+- define adjustment variables a priori;
+- account for clustering or stratification;
+- avoid interpreting `1 − HR` as a reduction in cumulative risk.
+
+If proportional hazards is doubtful, consider:
+
+- time-varying coefficients;
+- piecewise effects;
+- landmark effects;
+- restricted mean survival time at a justified horizon;
+- survival or cumulative-incidence differences at prespecified times;
+- accelerated failure-time or flexible parametric models.
+
+Report why the selected summary answers the research question.
+
+## Competing Risks
+
+Distinguish:
+
+- cause-specific hazard questions;
+- cumulative-incidence/absolute-risk questions;
+- subdistribution-hazard modeling.
+
+State which question the method answers. A subdistribution hazard ratio is not directly a risk ratio. When modeling several event types, check that resulting probability estimates are coherent.
+
+Primary reference: [Austin, Lee, and Fine, competing risks](https://pubmed.ncbi.nlm.nih.gov/26858290/).
+
+## Bias and Missingness
+
+Plan for:
+
+- informative censoring;
+- delayed entry/left truncation;
+- immortal time;
+- time-dependent confounding;
+- interval censoring;
+- outcome misclassification;
+- missing covariates;
+- competing events;
+- informative visit schedules;
+- treatment switching and rescue treatment;
+- site and calendar effects.
+
+Specify sensitivity analyses tied to plausible departures from assumptions. A “best/worst case” alone is rarely sufficient.
+
+## Prediction Models
+
+For time-to-event prediction:
+
+- preserve the locked model and prediction horizon;
+- evaluate calibration at prespecified times;
+- report time-dependent discrimination with uncertainty;
+- use appropriate handling of censoring;
+- evaluate overall and subgroup performance;
+- perform external validation in relevant settings;
+- avoid selecting a horizon after viewing results.
+
+Use TRIPOD+AI and PROBAST+AI.
+
+## Biomarker Evaluation
+
+For a prognostic biomarker:
+
+- analyze continuous form where scientifically justified;
+- pre-specify transformations and threshold;
+- avoid minimum-p-value cut-point searches;
+- report assay and specimen handling;
+- adjust for established prognostic factors;
+- validate externally.
+
+For a predictive biomarker, estimate and report a treatment-by-biomarker interaction in an appropriate design. Separate prognostic association from treatment-effect modification.
+
+## Uncertainty and Multiplicity
+
+Include:
+
+- confidence intervals for every primary effect;
+- uncertainty in calibration/discrimination;
+- prespecified alpha or interval interpretation;
+- multiplicity strategy for outcomes, times, subgroups, and models;
+- bootstrap or cross-validation details if used;
+- sensitivity analyses;
+- model optimism and overfitting assessment.
+
+Do not turn a threshold-crossing p-value into clinical importance.
+
+## Primary Method Sources
+
+- [ICH E9(R1) estimands and sensitivity analysis](https://database.ich.org/sites/default/files/E9-R1_Step4_Guideline_2019_1203.pdf)
+- [Royston and Parmar, restricted mean survival time](https://pubmed.ncbi.nlm.nih.gov/24314264/)
+- [Austin and Fine, reporting competing-risk analyses](https://pmc.ncbi.nlm.nih.gov/articles/PMC5698744/)
+
+## Plan Validator
+
+```bash
+python3 scripts/survival_plan_validator.py assets/survival_analysis_plan_template.json
+```
+
+An exit code of zero means required planning fields and selected consistency rules passed. It is not statistical approval.