@pikaa-ai/pikaa 0.3.1 → 0.3.4

package/skills/treatment-plans/references/documentation_workflow.md

@@ -1,165 +0,0 @@
-# Documentation Package Workflow
-
-Last reviewed: **2026-07-23**
-
-## Package contract
-
-A complete package contains exactly one JSON object for each document type:
-
-- `source_fact_manifest`
-- `clinician_authored_intervention_record`
-- `goals_monitoring_checkpoint_record`
-- `informed_preference_shared_decision_record`
-- `transition_reconciliation_record`
-- `intended_use_handoff_record`
-
-All six must use schema version `2.0` and the same `subject_ref`, `data_classification`, draft status, and notice.
-
-## 1. Intended-use gate
-
-Complete the intended-use/handoff record first:
-
-- purpose and authorized users;
-- local setting and accountable roles;
-- prohibited-use list;
-- privacy and processing attestations;
-- local policy, retention, change-control, and reporting routes;
-- local emergency-process reference;
-- handoff sender, recipient, and acknowledgment;
-- clinician sign-off and documentation-handoff release gate.
-
-Do not remove prohibited uses. The generator restores the complete list in every new package.
-
-## 2. Source-fact manifest
-
-Every clinical or process statement used elsewhere must have a source fact. A fact records:
-
-- a stable fact ID;
-- fact kind;
-- the exact bounded statement supplied;
-- source type, title, local locator, and version/date;
-- verification status, verifier role, and time;
-- applicability status when an official source or policy is involved.
-
-Allowed source categories distinguish signed local records, authorized EHR records, current FDA labeling, current REMS materials, current official guidance, and local policy.
-
-The manifest does not decide which source applies. An authorized professional must confirm applicability.
-
-## 3. Clinician-authored interventions
-
-Each intervention record must:
-
-- state that the decision was supplied and verified by an authorized licensed professional;
-- preserve the clinician-authored action without rewriting it into a recommendation;
-- link to at least one verified source fact;
-- record parameters only as supplied;
-- identify the responsible role;
-- preserve explicit start/end dates when supplied;
-- include verifier role and time.
-
-The validator checks structure and provenance only. It does not parse or judge a medication, procedure, therapy, device, referral, or instruction.
-
-## 4. Goals, monitoring, and checkpoints
-
-Separate:
-
-- goals — statement, measurement, target, target date, and source facts;
-- monitoring items — item, method, supplied frequency text, explicit next due date, owner, and source facts;
-- checkpoints — exact supplied date, purpose, owner, linked records, and source facts.
-
-Do not convert a narrative frequency into dates. Do not infer a checkpoint from a target, medication, intervention type, standard interval, or prior appointment.
-
-## 5. Informed preferences and shared decisions
-
-Record only what the authorized clinician documented:
-
-- decision topic;
-- options actually presented;
-- whether benefits, harms, and uncertainty were documented;
-- the person's stated preference;
-- the clinician-documented outcome;
-- participant and author roles;
-- source facts, time, and acknowledgment status.
-
-Do not generate missing options, risk estimates, benefit claims, alternatives, or consent language.
-
-## 6. Transition and reconciliation
-
-Record:
-
-- sending and receiving settings and roles;
-- exact handoff date;
-- medication-reconciliation status;
-- source and destination list fact references;
-- discrepancy status and authorized reviewer;
-- handoff items, owners, recipients, and acknowledgment;
-- unresolved items and their local route.
-
-`completed_by_authorized_clinician` is a declaration to be verified against the local record. The script does not perform reconciliation.
-
-## 7. Deterministic checks
-
-Run in this order:
-
-```bash
-python3 scripts/validate_treatment_plan.py PACKAGE_DIRECTORY
-python3 scripts/validate_traceability.py PACKAGE_DIRECTORY
-python3 scripts/check_completeness.py PACKAGE_DIRECTORY
-python3 scripts/privacy_process_check.py PACKAGE_DIRECTORY
-python3 scripts/check_consistency.py PACKAGE_DIRECTORY
-python3 scripts/timeline_generator.py PACKAGE_DIRECTORY --output SCHEDULE.json
-```
-
-The checks answer different questions:
-
-- structural validator — are document types, fields, types, enums, bounds, and dates valid?
-- traceability validator — do all clinical/process records point to existing verified facts?
-- completeness checker — are required records, reviews, routes, acknowledgments, sign-off, and release declarations complete?
-- privacy/process checker — are local authorization, minimization, external-tool prohibition, qualified review, retention, and direct-identifier safeguards documented?
-- consistency checker — do package IDs, statuses, classifications, references, and explicit date order agree?
-- timeline generator — what events occur on dates already supplied?
-
-Run every check again after any change.
-
-## 8. Minimized issue handling
-
-Reports use field paths, not values. For example, a report may identify `interventions[0].verification.status` without printing the action text.
-
-Resolve each issue in the authoritative local record:
-
-1. Locate the field path.
-2. Compare with the signed source.
-3. Ask the responsible authorized role to supply or verify the missing value.
-4. Update provenance.
-5. Re-run all checks.
-
-Never correct clinical content from memory or general guidance.
-
-## 9. Sign-off and handoff
-
-Before releasing for authorized documentation handoff:
-
-- all source facts are verified;
-- source applicability is confirmed where required;
-- interventions are verified;
-- reconciliation is completed or explicitly not applicable by an authorized reviewer;
-- unresolved items are routed and acknowledged;
-- privacy/process review is complete;
-- local policy and reporting routes are populated;
-- the recipient is identified;
-- the authorized licensed signer completes the attestation;
-- the release gate is set to `released_for_authorized_documentation_handoff`;
-- blocker codes are empty.
-
-The visible draft/not-medical-advice notice remains. Release does not authorize implementation by an agent.
-
-## 10. Change control
-
-For every revision:
-
-- preserve the prior authorized version according to local records policy;
-- update source versions and verification times;
-- re-run every check;
-- obtain new sign-off when clinical content, recipient, classification, purpose, or governing source changes;
-- record disposition of superseded local copies;
-- never overwrite a source record or silently reuse an old approval.

package/skills/treatment-plans/references/privacy_governance.md

@@ -1,119 +0,0 @@
-# Privacy and Data Governance
-
-Last reviewed: **2026-07-23**
-
-## No compliance claim
-
-Passing a template or script does not establish de-identification, HIPAA compliance, authorization, lawful disclosure, security, or appropriate retention. Those determinations belong to qualified local privacy, security, legal, and records personnel.
-
-## Data classes
-
-Use exactly one package-wide classification:
-
-- `synthetic` — invented records with no relationship to a real person.
-- `deidentified_qualified_review` — patient-derived information that a qualified reviewer has approved under the applicable method and context.
-- `real_patient_minimum_necessary` — identifiable or potentially identifiable data handled only in an authorized local environment.
-
-Never relabel real data as synthetic. Hashing, pseudonymization, redaction of obvious fields, using a patient code, or removing direct identifiers does not by itself make data de-identified.
-
-## HHS de-identification boundary
-
-HHS describes two HIPAA Privacy Rule methods:
-
-1. **Expert Determination** — a qualified expert determines that re-identification risk is very small and documents methods and results.
-2. **Safe Harbor** — specified identifiers are removed and the covered entity lacks actual knowledge that remaining information could identify an individual.
-
-This skill performs neither method. Free text, dates, geography, rare combinations, longitudinal patterns, and other contextual information can retain identification risk. HHS specifically notes that clinical narratives are information-rich and may allow identification.
-
-For patient-derived material:
-
-- document which method and policy were applied;
-- record the qualified reviewer's role, review date, scope, assumptions, and expiration or re-review condition;
-- keep the determination and supporting analysis in the authorized local system;
-- re-review after material data, recipient, linkage, technology, or purpose changes;
-- treat uncertainty as a release blocker.
-
-Do not place a de-identification analysis or patient-derived examples in this repository.
-
-## Minimum-necessary handling
-
-HHS states that the HIPAA minimum necessary standard generally requires reasonable steps to limit uses, disclosures, and requests for protected health information, while identifying exceptions including disclosures to or requests by a healthcare provider for treatment.
-
-This skill does not decide whether an exception applies. As a conservative process safeguard, always minimize what enters the package and follow the institution's current role-based access and disclosure policies.
-
-Record:
-
-- the specific documentation purpose;
-- authorized users and recipient;
-- required data categories;
-- excluded data categories;
-- local authorization and environment references;
-- retention and disposition requirements;
-- who approved any exception or broader access.
-
-## Real-patient gate
-
-Before any real-patient package is opened:
-
-1. Confirm local authorization and an approved environment.
-2. Confirm the accountable clinical and privacy owners.
-3. Confirm the minimum-necessary field set and intended recipient.
-4. Confirm no external service, model, API, search, telemetry, image, or cloud-processing step will receive content.
-5. Confirm content will not be copied into prompts, logs, examples, tests, screenshots, issue reports, or commit messages.
-6. Confirm retention, deletion, access, and incident-response rules.
-7. Run only local standard-library scripts against file paths.
-
-If any confirmation is absent, use synthetic templates and stop before reading values.
-
-## Structured-data preference
-
-Prefer discrete identifiers, enums, dates, booleans, role labels, and source references. Use bounded clinician-authored text only where exact transcription is necessary.
-
-Avoid:
-
-- copied progress notes, discharge narratives, portal messages, or full record exports;
-- names, addresses, contact information, dates of birth, medical-record numbers, account numbers, images, biometrics, or device identifiers;
-- exact free-text descriptions when a structured status or local record locator is sufficient;
-- patient details in filenames or directory names.
-
-The generic `subject_ref` must be a locally controlled pseudonymous reference. It is not proof of de-identification.
-
-## Report minimization
-
-Bundled scripts must not echo clinical values. Reports are limited to:
-
-- rule codes;
-- pass/fail status;
-- document types;
-- field paths;
-- counts;
-- nonclinical dates already needed for a schedule;
-- local filenames without parent-directory expansion.
-
-Do not run scripts with shell tracing. Do not redirect reports to shared logs. Review local command history policies before working with sensitive paths.
-
-## Local path controls
-
-The scripts:
-
-- reject URL-like input paths and network-share syntax;
-- reject symlink inputs and outputs;
-- accept only bounded regular UTF-8 JSON files;
-- reject duplicate keys, excessive nesting, oversized text, excessive records, and unknown fields;
-- create private outputs without implicit overwrite;
-- do not inspect environment variables or credential files.
-
-These are defense-in-depth controls, not privacy determinations.
-
-## Incident routing
-
-If accidental disclosure, unauthorized access, or suspected mishandling occurs:
-
-- stop processing;
-- preserve only what local policy requires;
-- use the institution's current privacy/security incident route;
-- do not investigate by copying content into another tool;
-- do not decide whether an event is reportable;
-- record the responsible role and local case/reference number only after authorization.
-
-HHS OCR breach reporting sources are listed in `source_ledger.md`. The skill does not file reports.

package/skills/treatment-plans/references/safety_scope.md

@@ -1,101 +0,0 @@
-# Safety, Scope, and Routing
-
-Last reviewed: **2026-07-23**
-
-## Purpose
-
-This skill is a transcription, formatting, provenance, and process-validation aid. It accepts clinical decisions only after an authorized licensed professional has made and verified them in a current local source.
-
-The skill is not a clinical decision-support system, medical device, prescribing tool, medication checker, triage service, or patient education service.
-
-## Prohibited functions
-
-Do not:
-
-- identify or infer a diagnosis, differential, severity, stage, risk class, or eligibility;
-- propose, compare, rank, select, substitute, or optimize a treatment;
-- generate medication names, doses, routes, frequencies, durations, start dates, stop dates, hold criteria, titration steps, or taper schedules;
-- judge an interaction, allergy, contraindication, precaution, organ-function issue, pregnancy issue, or formulary suitability;
-- generate a monitoring parameter, target, threshold, interval, follow-up frequency, or escalation criterion;
-- interpret a symptom, test, image, score, trend, medication list, adverse event, or patient preference;
-- determine urgency, triage disposition, emergency status, prognosis, expected response, or likely outcome;
-- create patient-specific instructions, education, warning signs, crisis plans, or emergency actions;
-- recommend a specialist, setting, service level, procedure, device, or referral;
-- certify compliance, clinical completeness, standard of care, informed consent, capacity, or professional scope.
-
-Formatting a supplied decision does not validate it. A citation does not make a decision current or applicable.
-
-## Request handling
-
-Proceed only when the request is equivalent to:
-
-- "Place these already signed clinician decisions into the generic records."
-- "Check whether this local JSON package has the required fields."
-- "Verify that every record points to a verified source fact."
-- "List checkpoints on the exact dates already provided."
-- "Identify missing acknowledgments or sign-off fields without suggesting clinical content."
-
-Stop and route when the request asks:
-
-- "What should the plan be?"
-- "What treatment, medication, dose, or schedule is best?"
-- "Should this be started, stopped, held, resumed, increased, reduced, or tapered?"
-- "Are these medicines safe together or contraindicated?"
-- "Is this urgent, an emergency, or likely to worsen?"
-- "What should the patient do now?"
-
-Do not soften a prohibited request into a recommendation-shaped template. Do not ask another skill, model, search tool, or API to make the decision.
-
-## Missing or conflicting content
-
-When a required clinical field is missing:
-
-1. Leave it empty or mark the record pending.
-2. Record a nonclinical blocker code and field path.
-3. Route it to the responsible authorized professional.
-4. Do not infer a value from neighboring records, standard practice, prior examples, a product label, or a guideline.
-
-When sources conflict, record the conflict without deciding which source controls. The authorized local team must reconcile it in an approved system.
-
-## Emergency and escalation boundary
-
-Use this exact process statement:
-
-> If a concern may be urgent or emergent, stop this documentation workflow and use the institution's current clinical escalation or emergency process; this package does not determine urgency or provide emergency instructions.
-
-The package records only the local process reference and responsible role. It must not include generated symptom thresholds, emergency numbers, destinations, or action steps. Current institution-approved material may be linked by a local reference after authorized review.
-
-## Accountable roles
-
-At minimum, identify:
-
-- clinical owner — owns clinical decisions and conflict resolution;
-- authorized licensed verifier — compares transcribed content with current sources;
-- medication-reconciliation owner — performs reconciliation in approved systems;
-- privacy reviewer — reviews patient-derived data handling and de-identification claims;
-- records/governance owner — controls retention, access, versioning, and release;
-- handoff sender and recipient — own transfer and acknowledgment;
-- local reporting owner — determines whether and where an event must be reported.
-
-One person may hold multiple roles only if local policy permits it. A script can verify that roles are named; it cannot verify competence, licensure, authority, independence, or completion.
-
-## Release boundary
-
-The documentation package remains visibly marked:
-
-> **DRAFT — NOT MEDICAL ADVICE — DOCUMENTATION-ONLY — AUTHORIZED CLINICIAN SIGN-OFF REQUIRED**
-
-Release means only that the package may enter the authorized documentation handoff named in the manifest. It does not turn the package into stand-alone medical advice or authorize an agent to implement care.
-
-Block release when any of these remain:
-
-- unverified facts or interventions;
-- missing source links;
-- unresolved discrepancies not routed to an owner;
-- absent shared-decision documentation when required by the local workflow;
-- incomplete reconciliation;
-- missing privacy/process attestations;
-- missing current local policy or labeling verification;
-- missing handoff recipient or acknowledgment;
-- unsigned clinician attestation;
-- inconsistent subject reference, classification, status, or dates.

package/skills/treatment-plans/references/security_validation.md

@@ -1,68 +0,0 @@
-# Security Validation Record
-
-Validation date: **2026-07-23**
-
-## Baseline
-
-The repository `SECURITY.md` entry recorded **11 findings** with maximum severity **CRITICAL**:
-
-- three CRITICAL cross-file/environment/network exfiltration findings;
-- one HIGH API-key transmission finding;
-- five MEDIUM findings involving environment harvesting, command chaining, and mandatory external-tool behavior;
-- two LOW findings involving unsafe template content and unpinned dependencies.
-
-The affected files included the former `generate_schematic.py`, `generate_schematic_ai.py`, `SKILL.md`, and `medical_treatment_plan.sty`.
-
-## Remediation
-
-- Deleted both schematic-generation scripts.
-- Removed network requests, API keys, environment access, `.env` loading, subprocesses, external models, image generation, and cross-skill calls.
-- Deleted the hardcoded LaTeX style and all specialty templates containing clinical treatment content.
-- Replaced them with generic, fail-closed JSON records.
-- Rebuilt every remaining script as a dependency-free, bounded, deterministic local JSON helper.
-- Added strict duplicate-key, schema, unknown-field, collection, depth, path, symlink, and output controls.
-- Added minimized reports that do not echo clinician-authored content.
-- Added AST tests prohibiting network libraries, dynamic execution, executable serialization, subprocesses, and environment access.
-
-## Validation results
-
-- Agent Skills reference validator: **PASS**
-- Dependency-free CLI help checks: **PASS**
-- Synthetic standard-library tests: **21 passed**
-- Explicit AST parse with bytecode disabled: **8 scripts parsed**
-- Bytecode artifacts after cleanup: **0**
-- IDE lints: **0**
-- Documented local-path check: **PASS**
-- External source links: **PASS** (HTTP 403 from HHS/AHRQ is access control; REMS@FDA returned HTTP 200 with a browser user agent)
-- Direct behavioral security scan: **SAFE, 0 findings**
-- Pull-request gate with `--fail-on HIGH`: **PASS**
-  - CRITICAL: 0
-  - HIGH: 0
-  - LOW: 2
-
-The first direct scan reported a CRITICAL test-only false positive because the synthetic AST test contained literal names for dynamic-execution functions and used a subprocess to exercise `--help`. The help test was changed to call each parser directly and the prohibited names were constructed without executable references. The final direct scan is clean.
-
-## Residual LOW findings
-
-The LLM-assisted pull-request scan reported:
-
-1. **Missing `allowed-tools` declaration** — informational. The field is optional. The compatibility statement and body explicitly limit bundled tools to local standard-library JSON processing, and the direct behavioral scan confirms no network, credential, process, model, or image behavior.
-2. **Invented missing-file variants** — scanner false positive. It claimed files under `templates/` and swapped `assets/` and `references/` paths that do not appear in the skill. The deterministic documented-local-path test resolves every actual local path and passes.
-
-Neither LOW finding permits data transmission or clinical decision-making. No actual CRITICAL or HIGH finding remains. The repository-level `SECURITY.md` is intentionally not edited in this scoped refresh; its generated snapshot will update through the repository's normal process.
-
-## Reproduction
-
-```bash
-PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover \
-  -s tests/treatment-plans -p 'test_*.py' -v
-
-uv run skills-ref validate skills/treatment-plans
-
-uv run skill-scanner scan skills/treatment-plans --use-behavioral
-
-uv run python scan_pr_skills.py \
-  --fail-on HIGH \
-  --output /tmp/treatment-plans-pr-scan.md \
-  skills/treatment-plans
-```

package/skills/treatment-plans/references/shared_decision_handoff.md

@@ -1,138 +0,0 @@
-# Shared Decisions, Informed Preferences, and Handoffs
-
-Last reviewed: **2026-07-23**
-
-## Documentation-only role
-
-AHRQ describes shared decision-making as a clinician-led process that explores options, benefits, harms, risks, and what matters to the person. NICE similarly describes healthcare professionals and people working together on treatment and care decisions and communicating risks, benefits, and consequences.
-
-This skill records that process after it occurred. It does not conduct the conversation, generate options, quantify risks, assess capacity, obtain consent, or decide the outcome.
-
-## Shared-decision record
-
-For each decision, the authorized clinician supplies:
-
-- the decision topic;
-- options actually presented;
-- source facts for each option;
-- whether benefits, harms, and uncertainty were discussed;
-- the preference as documented;
-- the agreed or clinician-recorded outcome;
-- participant roles;
-- author role and time;
-- acknowledgment status.
-
-Use the person's words only when necessary and permitted. Prefer a bounded structured summary over copied narrative.
-
-Do not:
-
-- add an option the clinician did not document;
-- characterize an option as preferred, safer, better, first-line, standard, or equivalent;
-- calculate or restate probabilities;
-- infer preference from adherence, demographics, prior care, or silence;
-- treat a checked box as proof of understanding, voluntariness, capacity, or informed consent;
-- create a consent form or legal attestation.
-
-## Informed preference versus informed consent
-
-The template documents an informed preference and shared-decision process. It does not replace:
-
-- jurisdiction-specific informed-consent requirements;
-- procedure- or product-specific consent;
-- capacity evaluation;
-- surrogate or guardian authority review;
-- language-access or accessibility requirements;
-- research consent;
-- local refusal or declination documentation.
-
-The authorized local team decides which separate records are required.
-
-## Communication quality
-
-The record may note whether the clinician documented:
-
-- benefits, harms, and material uncertainty;
-- alternatives, including no action, when actually discussed;
-- questions and responses;
-- language, interpreter, communication, or accessibility support;
-- decision aid identity and version;
-- need for revisiting the decision.
-
-Do not infer quality from presence alone. Do not score the conversation.
-
-## Transition handoff
-
-WHO transition guidance supports timely, accurate information transfer, medication reconciliation, patient/carer involvement, clear ownership, standardized processes, checklists, and tracking.
-
-A handoff record should identify:
-
-- sending and receiving settings and responsible roles;
-- exact handoff date supplied by the clinical team;
-- source records and their versions;
-- interventions, goals, monitoring, checkpoints, and pending results that were actually supplied;
-- ownership of each item;
-- reconciliation status;
-- unresolved items and route;
-- sender and recipient acknowledgment;
-- local follow-up and escalation references.
-
-The skill does not decide which clinical items are important enough to hand off. The responsible clinicians do.
-
-## Medication reconciliation boundary
-
-Medication reconciliation is a clinical process, not a list-diff script. The authorized team must obtain and compare the relevant lists, make clinical decisions about discrepancies, communicate the result, and document completion in approved systems.
-
-This package may record:
-
-- source-list fact IDs;
-- destination-list fact IDs;
-- `pending_authorized_review`, `completed_by_authorized_clinician`, or `not_applicable`;
-- discrepancy status;
-- reviewer role and completion time.
-
-It must not:
-
-- parse medication text to normalize products;
-- identify duplicates, interactions, contraindications, omissions, or dose differences;
-- decide which list is correct;
-- propose changes;
-- mark reconciliation complete automatically.
-
-If a discrepancy is detected outside the authorized clinical workflow, leave it unresolved and route it to the named medication-reconciliation owner.
-
-## Pending and unresolved items
-
-Every unresolved item needs:
-
-- a stable item ID;
-- a bounded description supplied by the local team;
-- source-fact references;
-- responsible local role;
-- route status.
-
-An item may be `open_routed`, `acknowledged_by_owner`, or `resolved_by_authorized_professional`. The skill never selects the owner or resolution.
-
-## Emergency routing
-
-Do not include generated warning signs, thresholds, destinations, emergency numbers, or instructions.
-
-Record only:
-
-> If a concern may be urgent or emergent, stop this documentation workflow and use the institution's current clinical escalation or emergency process; this package does not determine urgency or provide emergency instructions.
-
-The authorized institution supplies and verifies the local process reference.
-
-## Handoff release
-
-Before authorized documentation handoff:
-
-- source and destination roles are named;
-- all included items link to verified facts;
-- reconciliation status is verified;
-- unresolved items are routed;
-- the recipient acknowledgment is complete;
-- privacy and local governance checks pass;
-- the clinician sign-off is complete;
-- the release gate has no blocker codes.
-
-These gates document process completion. They do not prove safe care, successful communication, or recipient action.