Skip to content

K-Dense-AI/scientific-agent-skills / skills/treatment-plans

treatment-plans

Verified

Formats and structurally validates local treatment-plan documentation after clinical decisions have already been supplied and verified by authorized licensed professionals. Use for source traceability, clinician-authored intervention records, goals and checkpoints, shared-decision records, reconciliation handoffs, and release gates—not for clinical decision-making.

scripts/_common.py

View on GitHub
#!/usr/bin/env python3
"""Bounded, dependency-free helpers for local treatment-plan JSON records."""

from __future__ import annotations

import json
import os
import re
import tempfile
from dataclasses import dataclass
from datetime import date, datetime
from pathlib import Path
from typing import Any, Iterable

SCHEMA_VERSION = "2.0"
STATUS = "DRAFT_NOT_FOR_CLINICAL_USE"
NOTICE = (
    "DRAFT — NOT MEDICAL ADVICE — DOCUMENTATION-ONLY — "
    "AUTHORIZED CLINICIAN SIGN-OFF REQUIRED"
)
EMERGENCY_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."
)
SIGNOFF_ATTESTATION = (
    "The signer attests only that this package accurately transcribes "
    "clinician-supplied and verified decisions for authorized documentation "
    "handoff; it is not stand-alone medical advice."
)

MAX_INPUT_BYTES = 2 * 1024 * 1024
MAX_TEXT_CHARS = 8_000
MAX_LIST_ITEMS = 500
MAX_OBJECT_FIELDS = 100
MAX_DEPTH = 20
MAX_TOTAL_NODES = 20_000

IDENTIFIER_RE = re.compile(r"^[A-Za-z][A-Za-z0-9._:-]{1,95}$")
DATETIME_RE = re.compile(
    r"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}"
    r"(?:\.[0-9]{1,6})?(?:Z|[+-](?:[01][0-9]|2[0-3]):[0-5][0-9])"
)
BLOCKER_RE = re.compile(r"^[A-Z][A-Z0-9_]{2,95}$")
DIRECT_IDENTIFIER_KEYS = {
    "address",
    "date_of_birth",
    "dob",
    "email",
    "fax",
    "full_name",
    "medical_record_number",
    "mrn",
    "name",
    "patient_id",
    "phone",
    "social_security_number",
    "ssn",
}
PROHIBITED_USES = {
    "diagnosis_or_assessment",
    "therapy_selection_or_recommendation",
    "medication_or_dose_decision",
    "start_stop_hold_resume_titrate_or_taper_decision",
    "interaction_allergy_or_contraindication_check",
    "triage_or_urgency_determination",
    "emergency_advice_or_safety_plan",
    "prognosis_or_outcome_prediction",
    "patient_specific_recommendation",
    "replacement_of_authorized_professional_review",
}

TEMPLATE_FILES = {
    "source_fact_manifest": (
        "source_fact_manifest_template.json",
        "source_fact_manifest.json",
    ),
    "clinician_authored_intervention_record": (
        "clinician_authored_intervention_template.json",
        "clinician_authored_intervention.json",
    ),
    "goals_monitoring_checkpoint_record": (
        "goals_monitoring_checkpoint_template.json",
        "goals_monitoring_checkpoint.json",
    ),
    "informed_preference_shared_decision_record": (
        "informed_preference_shared_decision_template.json",
        "informed_preference_shared_decision.json",
    ),
    "transition_reconciliation_record": (
        "transition_reconciliation_template.json",
        "transition_reconciliation.json",
    ),
    "intended_use_handoff_record": (
        "intended_use_handoff_template.json",
        "intended_use_handoff.json",
    ),
}


class ValidationError(ValueError):
    """A deterministic failure that never includes a clinical value."""

    def __init__(self, code: str, path: str = "$") -> None:
        super().__init__(code)
        self.code = code
        self.path = path


@dataclass(frozen=True)
class Issue:
    """A minimized validation issue."""

    code: str
    path: str
    level: str = "error"

    def as_dict(self) -> dict[str, str]:
        return {"code": self.code, "path": self.path, "level": self.level}


def _text(
    *,
    minimum: int = 0,
    maximum: int = MAX_TEXT_CHARS,
    enum: Iterable[str] | None = None,
    const: str | None = None,
    pattern: str | None = None,
    format_name: str | None = None,
) -> dict[str, Any]:
    return {
        "kind": "string",
        "minimum": minimum,
        "maximum": maximum,
        "enum": set(enum) if enum is not None else None,
        "const": const,
        "pattern": re.compile(pattern) if pattern else None,
        "format": format_name,
    }


def _boolean() -> dict[str, str]:
    return {"kind": "boolean"}


def _nullable(schema: dict[str, Any]) -> dict[str, Any]:
    return {"kind": "nullable", "schema": schema}


def _array(
    item: dict[str, Any], *, minimum: int = 0, maximum: int = MAX_LIST_ITEMS
) -> dict[str, Any]:
    return {
        "kind": "array",
        "item": item,
        "minimum": minimum,
        "maximum": maximum,
    }


def _object(properties: dict[str, dict[str, Any]]) -> dict[str, Any]:
    return {"kind": "object", "properties": properties}


IDENTIFIER = _text(minimum=2, maximum=96, pattern=IDENTIFIER_RE.pattern)
ROLE = _text(maximum=200)
NONEMPTY_ROLE = _text(minimum=1, maximum=200)
DATE = _text(minimum=10, maximum=10, format_name="date")
DATETIME = _text(minimum=20, maximum=40, format_name="datetime")
FACT_IDS = _array(IDENTIFIER, minimum=1, maximum=100)

HEADER = {
    "schema_version": _text(const=SCHEMA_VERSION),
    "document_type": _text(minimum=1, maximum=96),
    "document_id": IDENTIFIER,
    "subject_ref": IDENTIFIER,
    "data_classification": _text(
        enum={
            "synthetic",
            "deidentified_qualified_review",
            "real_patient_minimum_necessary",
        }
    ),
    "status": _text(const=STATUS),
    "notice": _text(const=NOTICE),
    "created_at": _nullable(DATETIME),
}

VERIFICATION = _object(
    {
        "status": _text(enum={"pending", "verified"}),
        "verified_by_role": ROLE,
        "verified_at": _nullable(DATETIME),
    }
)

SOURCE_FACT_SCHEMA = _object(
    {
        "fact_id": IDENTIFIER,
        "fact_kind": _text(
            enum={
                "clinician_authored_decision",
                "verified_local_record",
                "current_official_source",
                "local_policy",
            }
        ),
        "statement_as_supplied": _text(minimum=1, maximum=4_000),
        "source": _object(
            {
                "source_type": _text(
                    enum={
                        "signed_clinician_record",
                        "authorized_ehr_record",
                        "current_fda_labeling",
                        "current_rems_material",
                        "current_official_guidance",
                        "local_policy",
                    }
                ),
                "title": _text(minimum=1, maximum=500),
                "locator": _text(minimum=1, maximum=1_000),
                "version_or_date": _text(minimum=1, maximum=200),
            }
        ),
        "verification": VERIFICATION,
        "applicability": _object(
            {
                "status": _text(
                    enum={
                        "not_assessed",
                        "confirmed_by_authorized_clinician",
                        "not_applicable_local_record",
                    }
                ),
                "confirmed_by_role": ROLE,
                "confirmed_at": _nullable(DATETIME),
            }
        ),
    }
)

PARAMETER_SCHEMA = _object(
    {
        "parameter_id": IDENTIFIER,
        "label": _text(minimum=1, maximum=200),
        "value_as_supplied": _text(minimum=1, maximum=1_000),
        "source_fact_ids": FACT_IDS,
    }
)

INTERVENTION_SCHEMA = _object(
    {
        "intervention_id": IDENTIFIER,
        "intervention_kind": _text(
            enum={
                "medication",
                "procedure",
                "therapy",
                "diagnostic",
                "education",
                "care_coordination",
                "equipment_or_service",
                "other_clinician_authored",
            }
        ),
        "clinical_decision_status": _text(
            enum={
                "pending_authorized_verification",
                "supplied_and_verified_by_authorized_clinician",
            }
        ),
        "clinician_authored_action": _text(minimum=1, maximum=4_000),
        "parameters_as_supplied": _array(PARAMETER_SCHEMA, maximum=100),
        "source_fact_ids": FACT_IDS,
        "owner_role": NONEMPTY_ROLE,
        "start_date": _nullable(DATE),
        "end_date": _nullable(DATE),
        "verification": VERIFICATION,
    }
)

GOAL_SCHEMA = _object(
    {
        "goal_id": IDENTIFIER,
        "statement_as_supplied": _text(minimum=1, maximum=2_000),
        "measurement_as_supplied": _text(maximum=1_000),
        "target_as_supplied": _text(maximum=1_000),
        "target_date": _nullable(DATE),
        "source_fact_ids": FACT_IDS,
        "verified_by_role": NONEMPTY_ROLE,
    }
)

MONITORING_SCHEMA = _object(
    {
        "monitoring_id": IDENTIFIER,
        "item_as_supplied": _text(minimum=1, maximum=2_000),
        "method_as_supplied": _text(maximum=1_000),
        "frequency_as_supplied": _text(maximum=1_000),
        "next_due_date": _nullable(DATE),
        "owner_role": NONEMPTY_ROLE,
        "source_fact_ids": FACT_IDS,
    }
)

CHECKPOINT_SCHEMA = _object(
    {
        "checkpoint_id": IDENTIFIER,
        "checkpoint_date": DATE,
        "purpose_as_supplied": _text(minimum=1, maximum=2_000),
        "owner_role": NONEMPTY_ROLE,
        "linked_goal_ids": _array(IDENTIFIER, maximum=100),
        "linked_intervention_ids": _array(IDENTIFIER, maximum=100),
        "source_fact_ids": FACT_IDS,
    }
)

OPTION_SCHEMA = _object(
    {
        "option_id": IDENTIFIER,
        "option_as_documented": _text(minimum=1, maximum=2_000),
        "source_fact_ids": FACT_IDS,
    }
)

SHARED_DECISION_SCHEMA = _object(
    {
        "decision_id": IDENTIFIER,
        "decision_topic_as_documented": _text(minimum=1, maximum=2_000),
        "options_as_documented": _array(OPTION_SCHEMA, minimum=1, maximum=50),
        "benefits_harms_uncertainty_documented": _boolean(),
        "preference_as_documented": _text(maximum=2_000),
        "outcome_as_documented": _text(maximum=2_000),
        "outcome_source_fact_ids": FACT_IDS,
        "decision_status": _text(
            enum={
                "pending_clinician_documentation",
                "documented_by_authorized_clinician",
            }
        ),
        "participant_roles": _array(
            _text(minimum=1, maximum=200), minimum=1, maximum=20
        ),
        "documented_by_role": ROLE,
        "documented_at": _nullable(DATETIME),
        "acknowledgment_status": _text(
            enum={
                "pending",
                "acknowledged",
                "not_applicable_by_authorized_clinician",
            }
        ),
    }
)

HANDOFF_ITEM_SCHEMA = _object(
    {
        "item_id": IDENTIFIER,
        "category": _text(
            enum={
                "medications",
                "interventions",
                "goals",
                "monitoring",
                "pending_results",
                "appointments",
                "equipment_or_services",
                "preferences_or_access_needs",
                "local_process_reference",
                "other_clinician_supplied",
            }
        ),
        "summary_as_supplied": _text(minimum=1, maximum=2_000),
        "source_fact_ids": FACT_IDS,
        "owner_role": NONEMPTY_ROLE,
        "recipient_role": NONEMPTY_ROLE,
        "acknowledgment_status": _text(
            enum={
                "pending",
                "acknowledged",
                "not_applicable_by_authorized_role",
            }
        ),
    }
)

UNRESOLVED_ITEM_SCHEMA = _object(
    {
        "item_id": IDENTIFIER,
        "issue_as_documented": _text(minimum=1, maximum=2_000),
        "source_fact_ids": FACT_IDS,
        "routed_to_local_role": ROLE,
        "status": _text(
            enum={
                "open_unrouted",
                "open_routed",
                "acknowledged_by_owner",
                "resolved_by_authorized_professional",
            }
        ),
    }
)

DOCUMENT_SCHEMAS = {
    "source_fact_manifest": _object(
        {
            **HEADER,
            "document_type": _text(const="source_fact_manifest"),
            "facts": _array(SOURCE_FACT_SCHEMA, maximum=500),
        }
    ),
    "clinician_authored_intervention_record": _object(
        {
            **HEADER,
            "document_type": _text(
                const="clinician_authored_intervention_record"
            ),
            "interventions": _array(INTERVENTION_SCHEMA, maximum=200),
        }
    ),
    "goals_monitoring_checkpoint_record": _object(
        {
            **HEADER,
            "document_type": _text(
                const="goals_monitoring_checkpoint_record"
            ),
            "goals": _array(GOAL_SCHEMA, maximum=200),
            "monitoring_items": _array(MONITORING_SCHEMA, maximum=300),
            "checkpoints": _array(CHECKPOINT_SCHEMA, maximum=500),
        }
    ),
    "informed_preference_shared_decision_record": _object(
        {
            **HEADER,
            "document_type": _text(
                const="informed_preference_shared_decision_record"
            ),
            "entries": _array(SHARED_DECISION_SCHEMA, maximum=100),
        }
    ),
    "transition_reconciliation_record": _object(
        {
            **HEADER,
            "document_type": _text(const="transition_reconciliation_record"),
            "transition": _object(
                {
                    "from_setting_as_documented": _text(maximum=500),
                    "to_setting_as_documented": _text(maximum=500),
                    "handoff_date": _nullable(DATE),
                    "responsible_sender_role": ROLE,
                    "responsible_receiver_role": ROLE,
                }
            ),
            "medication_reconciliation": _object(
                {
                    "status": _text(
                        enum={
                            "pending_authorized_review",
                            "completed_by_authorized_clinician",
                            "not_applicable_by_authorized_clinician",
                        }
                    ),
                    "source_list_fact_ids": _array(
                        IDENTIFIER, maximum=200
                    ),
                    "destination_list_fact_ids": _array(
                        IDENTIFIER, maximum=200
                    ),
                    "discrepancy_status": _text(
                        enum={
                            "not_assessed",
                            "none_documented",
                            "routed_to_authorized_clinician",
                            "resolved_by_authorized_clinician",
                        }
                    ),
                    "completed_by_role": ROLE,
                    "completed_at": _nullable(DATETIME),
                }
            ),
            "handoff_items": _array(HANDOFF_ITEM_SCHEMA, maximum=300),
            "unresolved_items": _array(
                UNRESOLVED_ITEM_SCHEMA, maximum=200
            ),
        }
    ),
    "intended_use_handoff_record": _object(
        {
            **HEADER,
            "document_type": _text(const="intended_use_handoff_record"),
            "intended_use": _object(
                {
                    "purpose": _text(
                        const=(
                            "format_and_validate_clinician_supplied_plan_"
                            "documentation"
                        )
                    ),
                    "intended_users": _array(
                        _text(minimum=1, maximum=200), maximum=50
                    ),
                    "intended_setting": _text(maximum=500),
                    "output_role": _text(const="documentation_only"),
                    "prohibited_uses": _array(
                        _text(enum=PROHIBITED_USES),
                        minimum=len(PROHIBITED_USES),
                        maximum=len(PROHIBITED_USES),
                    ),
                }
            ),
            "privacy_process": _object(
                {
                    "data_classification": _text(
                        enum={
                            "synthetic",
                            "deidentified_qualified_review",
                            "real_patient_minimum_necessary",
                        }
                    ),
                    "local_authorization_confirmed": _boolean(),
                    "authorized_environment_reference": _text(
                        maximum=1_000
                    ),
                    "minimum_necessary_confirmed": _boolean(),
                    "no_external_tools_confirmed": _boolean(),
                    "no_prompt_log_example_copy_confirmed": _boolean(),
                    "privacy_review_status": _text(
                        enum={
                            "pending",
                            "not_applicable_synthetic",
                            "completed_by_qualified_reviewer",
                        }
                    ),
                    "privacy_reviewer_role": ROLE,
                    "reviewed_at": _nullable(DATETIME),
                    "retention_policy_reference": _text(maximum=1_000),
                    "data_disposition_status": _text(
                        enum={
                            "pending",
                            "retain_under_local_policy",
                            "delete_under_local_policy",
                            "completed_under_local_policy",
                        }
                    ),
                }
            ),
            "local_governance": _object(
                {
                    "institution_or_organization_reference": _text(
                        maximum=1_000
                    ),
                    "clinical_owner_role": ROLE,
                    "policy_references": _array(
                        _text(minimum=1, maximum=1_000), maximum=100
                    ),
                    "records_owner_role": ROLE,
                    "change_control_owner_role": ROLE,
                }
            ),
            "emergency_routing": _object(
                {
                    "statement": _text(const=EMERGENCY_STATEMENT),
                    "local_process_reference": _text(maximum=1_000),
                    "verified_by_role": ROLE,
                }
            ),
            "reporting_routes": _object(
                {
                    "local_patient_safety_route": _text(maximum=1_000),
                    "product_event_route": _text(maximum=1_000),
                    "privacy_incident_route": _text(maximum=1_000),
                    "responsible_role": ROLE,
                }
            ),
            "handoff": _object(
                {
                    "sender_role": ROLE,
                    "recipient_role": ROLE,
                    "sent_at": _nullable(DATETIME),
                    "acknowledgment_status": _text(
                        enum={"pending", "acknowledged"}
                    ),
                    "unresolved_items_routed": _boolean(),
                }
            ),
            "clinician_signoff": _object(
                {
                    "status": _text(enum={"pending", "signed"}),
                    "signer_role": ROLE,
                    "credential_authority_reference": _text(
                        maximum=1_000
                    ),
                    "signed_at": _nullable(DATETIME),
                    "attestation": _text(const=SIGNOFF_ATTESTATION),
                }
            ),
            "release_gate": _object(
                {
                    "status": _text(
                        enum={
                            "blocked",
                            "released_for_authorized_documentation_handoff",
                        }
                    ),
                    "released_by_role": ROLE,
                    "released_at": _nullable(DATETIME),
                    "blocker_codes": _array(
                        _text(
                            minimum=3,
                            maximum=96,
                            pattern=BLOCKER_RE.pattern,
                        ),
                        maximum=100,
                    ),
                }
            ),
        }
    ),
}


def _reject_nonlocal_path(raw_path: str | Path) -> Path:
    text = str(raw_path)
    lowered = text.strip().lower()
    if not lowered or "\x00" in text or "://" in lowered:
        raise ValidationError("NONLOCAL_OR_EMPTY_PATH")
    if lowered.startswith(("\\\\", "//")):
        raise ValidationError("NETWORK_SHARE_PATH_REJECTED")
    return Path(text).expanduser()


def safe_input_file(raw_path: str | Path) -> Path:
    """Resolve one bounded, regular, non-symlink local JSON file."""

    path = _reject_nonlocal_path(raw_path)
    if path.is_symlink():
        raise ValidationError("SYMLINK_INPUT_REJECTED")
    try:
        resolved = path.resolve(strict=True)
    except FileNotFoundError as exc:
        raise ValidationError("INPUT_FILE_MISSING", path.name) from exc
    if not resolved.is_file() or resolved.suffix.lower() != ".json":
        raise ValidationError("INPUT_MUST_BE_JSON_FILE", path.name)
    if resolved.stat().st_size > MAX_INPUT_BYTES:
        raise ValidationError("INPUT_FILE_TOO_LARGE", path.name)
    return resolved


def safe_input_directory(raw_path: str | Path) -> Path:
    """Resolve one local, non-symlink directory."""

    path = _reject_nonlocal_path(raw_path)
    if path.is_symlink():
        raise ValidationError("SYMLINK_DIRECTORY_REJECTED")
    try:
        resolved = path.resolve(strict=True)
    except FileNotFoundError as exc:
        raise ValidationError("INPUT_DIRECTORY_MISSING") from exc
    if not resolved.is_dir():
        raise ValidationError("INPUT_MUST_BE_DIRECTORY")
    return resolved


def safe_new_directory(raw_path: str | Path) -> Path:
    """Create a private directory without reusing an existing path."""

    path = _reject_nonlocal_path(raw_path)
    if path.exists() or path.is_symlink():
        raise ValidationError("OUTPUT_DIRECTORY_EXISTS")
    try:
        parent = path.parent.resolve(strict=True)
    except FileNotFoundError as exc:
        raise ValidationError("OUTPUT_PARENT_MISSING") from exc
    if not parent.is_dir():
        raise ValidationError("OUTPUT_PARENT_NOT_DIRECTORY")
    resolved = parent / path.name
    resolved.mkdir(mode=0o700)
    return resolved


def safe_output_file(raw_path: str | Path) -> Path:
    """Resolve a new local JSON output without implicit overwrite."""

    path = _reject_nonlocal_path(raw_path)
    if path.suffix.lower() != ".json":
        raise ValidationError("OUTPUT_MUST_BE_JSON")
    try:
        parent = path.parent.resolve(strict=True)
    except FileNotFoundError as exc:
        raise ValidationError("OUTPUT_PARENT_MISSING") from exc
    if not parent.is_dir():
        raise ValidationError("OUTPUT_PARENT_NOT_DIRECTORY")
    resolved = parent / path.name
    if resolved.exists() or resolved.is_symlink():
        raise ValidationError("OUTPUT_ALREADY_EXISTS", resolved.name)
    return resolved


def _duplicate_safe_object(
    pairs: list[tuple[str, Any]],
) -> dict[str, Any]:
    result: dict[str, Any] = {}
    for key, value in pairs:
        if key in result:
            raise ValidationError("JSON_DUPLICATE_KEY")
        result[key] = value
    return result


def _reject_constant(_: str) -> None:
    raise ValidationError("JSON_NONFINITE_NUMBER")


def _check_bounds(value: Any, *, depth: int = 0, counter: list[int]) -> None:
    if depth > MAX_DEPTH:
        raise ValidationError("JSON_MAX_DEPTH_EXCEEDED")
    counter[0] += 1
    if counter[0] > MAX_TOTAL_NODES:
        raise ValidationError("JSON_NODE_LIMIT_EXCEEDED")
    if isinstance(value, dict):
        if len(value) > MAX_OBJECT_FIELDS:
            raise ValidationError("JSON_OBJECT_FIELD_LIMIT_EXCEEDED")
        for key, nested in value.items():
            if not isinstance(key, str) or len(key) > 128:
                raise ValidationError("JSON_KEY_INVALID")
            _check_bounds(nested, depth=depth + 1, counter=counter)
    elif isinstance(value, list):
        if len(value) > MAX_LIST_ITEMS:
            raise ValidationError("JSON_LIST_LIMIT_EXCEEDED")
        for nested in value:
            _check_bounds(nested, depth=depth + 1, counter=counter)
    elif isinstance(value, str):
        if len(value) > MAX_TEXT_CHARS:
            raise ValidationError("JSON_TEXT_LIMIT_EXCEEDED")


def read_json(raw_path: str | Path) -> dict[str, Any]:
    """Read strict UTF-8 JSON without exposing values in failures."""

    path = safe_input_file(raw_path)
    try:
        with path.open("rb") as handle:
            raw = handle.read(MAX_INPUT_BYTES + 1)
        if len(raw) > MAX_INPUT_BYTES:
            raise ValidationError("INPUT_FILE_TOO_LARGE", path.name)
        text = raw.decode("utf-8")
    except UnicodeDecodeError as exc:
        raise ValidationError("JSON_NOT_UTF8", path.name) from exc
    except OSError as exc:
        raise ValidationError("INPUT_READ_FAILED", path.name) from exc
    if "\x00" in text:
        raise ValidationError("JSON_CONTAINS_NUL", path.name)
    try:
        value = json.loads(
            text,
            object_pairs_hook=_duplicate_safe_object,
            parse_constant=_reject_constant,
        )
    except json.JSONDecodeError as exc:
        raise ValidationError(
            "JSON_PARSE_ERROR", f"{path.name}:{exc.lineno}:{exc.colno}"
        ) from exc
    except RecursionError as exc:
        raise ValidationError("JSON_MAX_DEPTH_EXCEEDED") from exc
    except ValidationError:
        raise
    except ValueError as exc:
        raise ValidationError("JSON_NUMBER_INVALID") from exc
    if not isinstance(value, dict):
        raise ValidationError("JSON_ROOT_NOT_OBJECT", path.name)
    _check_bounds(value, counter=[0])
    return value


def load_package(
    raw_directory: str | Path,
) -> tuple[dict[str, dict[str, Any]], dict[str, Path]]:
    """Load the six required package records by fixed local filename."""

    root = safe_input_directory(raw_directory)
    documents: dict[str, dict[str, Any]] = {}
    paths: dict[str, Path] = {}
    for expected_type, (_, filename) in TEMPLATE_FILES.items():
        path = root / filename
        if not path.exists():
            raise ValidationError("PACKAGE_FILE_MISSING", filename)
        document = read_json(path)
        documents[expected_type] = document
        paths[expected_type] = path
    return documents, paths


def load_target(
    raw_path: str | Path, *, require_package: bool = False
) -> tuple[dict[str, dict[str, Any]], dict[str, Path]]:
    """Load one record or a complete package."""

    path = _reject_nonlocal_path(raw_path)
    if path.is_dir() and not path.is_symlink():
        return load_package(path)
    if require_package:
        raise ValidationError("PACKAGE_DIRECTORY_REQUIRED")
    document = read_json(path)
    document_type = document.get("document_type")
    if not isinstance(document_type, str):
        raise ValidationError("DOCUMENT_TYPE_MISSING")
    return {document_type: document}, {document_type: safe_input_file(path)}


def _valid_iso_date(value: str) -> bool:
    try:
        return date.fromisoformat(value).isoformat() == value
    except ValueError:
        return False


def parse_iso_datetime(value: str) -> datetime | None:
    """Parse an extended calendar datetime with seconds and an explicit offset."""

    if not isinstance(value, str) or DATETIME_RE.fullmatch(value) is None:
        return None
    try:
        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
    except ValueError:
        return None
    return parsed if parsed.tzinfo is not None else None


def _validate_schema(
    value: Any,
    schema: dict[str, Any],
    path: str,
    issues: list[Issue],
) -> None:
    kind = schema["kind"]
    if kind == "nullable":
        if value is None:
            return
        _validate_schema(value, schema["schema"], path, issues)
        return
    if kind == "object":
        if not isinstance(value, dict):
            issues.append(Issue("SCHEMA_TYPE_OBJECT", path))
            return
        properties = schema["properties"]
        for key in sorted(set(properties) - set(value)):
            issues.append(Issue("SCHEMA_REQUIRED_FIELD", f"{path}.{key}"))
        for _ in set(value) - set(properties):
            # Unknown keys may themselves contain identifying or clinical text.
            issues.append(Issue("SCHEMA_UNKNOWN_FIELD", f"{path}.[unknown_field]"))
        for key in properties.keys() & value.keys():
            _validate_schema(
                value[key], properties[key], f"{path}.{key}", issues
            )
        return
    if kind == "array":
        if not isinstance(value, list):
            issues.append(Issue("SCHEMA_TYPE_ARRAY", path))
            return
        if not schema["minimum"] <= len(value) <= schema["maximum"]:
            issues.append(Issue("SCHEMA_ARRAY_BOUNDS", path))
        for index, nested in enumerate(value):
            _validate_schema(
                nested, schema["item"], f"{path}[{index}]", issues
            )
        return
    if kind == "boolean":
        if type(value) is not bool:
            issues.append(Issue("SCHEMA_TYPE_BOOLEAN", path))
        return
    if kind == "string":
        if not isinstance(value, str):
            issues.append(Issue("SCHEMA_TYPE_STRING", path))
            return
        if not schema["minimum"] <= len(value) <= schema["maximum"]:
            issues.append(Issue("SCHEMA_STRING_BOUNDS", path))
        if schema["minimum"] and not value.strip():
            issues.append(Issue("SCHEMA_STRING_BLANK", path))
        if schema["const"] is not None and value != schema["const"]:
            issues.append(Issue("SCHEMA_CONST", path))
        if schema["enum"] is not None and value not in schema["enum"]:
            issues.append(Issue("SCHEMA_ENUM", path))
        if schema["pattern"] is not None and not schema["pattern"].fullmatch(
            value
        ):
            issues.append(Issue("SCHEMA_PATTERN", path))
        if schema["format"] == "date" and not _valid_iso_date(value):
            issues.append(Issue("SCHEMA_ISO_DATE", path))
        if schema["format"] == "datetime" and parse_iso_datetime(value) is None:
            issues.append(Issue("SCHEMA_ISO_DATETIME", path))
        return
    issues.append(Issue("SCHEMA_INTERNAL_KIND", path))


def _duplicate_field_issues(
    records: Any, field: str, path: str
) -> list[Issue]:
    if not isinstance(records, list):
        return []
    seen: set[str] = set()
    issues: list[Issue] = []
    for index, record in enumerate(records):
        if not isinstance(record, dict):
            continue
        value = record.get(field)
        if isinstance(value, str):
            if value in seen:
                issues.append(
                    Issue("DUPLICATE_RECORD_ID", f"{path}[{index}].{field}")
                )
            seen.add(value)
    return issues


def validate_document(
    document: dict[str, Any], expected_type: str | None = None
) -> list[Issue]:
    """Validate strict structure without evaluating clinical content."""

    document_type = document.get("document_type")
    if not isinstance(document_type, str):
        return [Issue("DOCUMENT_TYPE_MISSING", "$.document_type")]
    if expected_type is not None and document_type != expected_type:
        return [Issue("DOCUMENT_TYPE_FILENAME_MISMATCH", "$.document_type")]
    schema = DOCUMENT_SCHEMAS.get(document_type)
    if schema is None:
        return [Issue("DOCUMENT_TYPE_UNKNOWN", "$.document_type")]
    issues: list[Issue] = []
    _validate_schema(document, schema, "$", issues)

    if document_type == "source_fact_manifest":
        issues.extend(
            _duplicate_field_issues(document.get("facts"), "fact_id", "$.facts")
        )
    elif document_type == "clinician_authored_intervention_record":
        interventions = document.get("interventions")
        issues.extend(
            _duplicate_field_issues(
                interventions, "intervention_id", "$.interventions"
            )
        )
        if isinstance(interventions, list):
            for index, record in enumerate(interventions):
                if isinstance(record, dict):
                    issues.extend(
                        _duplicate_field_issues(
                            record.get("parameters_as_supplied"),
                            "parameter_id",
                            f"$.interventions[{index}].parameters_as_supplied",
                        )
                    )
    elif document_type == "goals_monitoring_checkpoint_record":
        for field, identifier_field in (
            ("goals", "goal_id"),
            ("monitoring_items", "monitoring_id"),
            ("checkpoints", "checkpoint_id"),
        ):
            issues.extend(
                _duplicate_field_issues(
                    document.get(field), identifier_field, f"$.{field}"
                )
            )
    elif document_type == "informed_preference_shared_decision_record":
        entries = document.get("entries")
        issues.extend(
            _duplicate_field_issues(entries, "decision_id", "$.entries")
        )
        if isinstance(entries, list):
            for index, record in enumerate(entries):
                if isinstance(record, dict):
                    issues.extend(
                        _duplicate_field_issues(
                            record.get("options_as_documented"),
                            "option_id",
                            f"$.entries[{index}].options_as_documented",
                        )
                    )
    elif document_type == "transition_reconciliation_record":
        for field in ("handoff_items", "unresolved_items"):
            issues.extend(
                _duplicate_field_issues(
                    document.get(field), "item_id", f"$.{field}"
                )
            )
    elif document_type == "intended_use_handoff_record":
        intended = document.get("intended_use")
        if isinstance(intended, dict):
            uses = intended.get("prohibited_uses")
            if isinstance(uses, list) and (
                any(not isinstance(item, str) for item in uses)
                or set(uses) != PROHIBITED_USES
            ):
                issues.append(
                    Issue(
                        "PROHIBITED_USE_SET_CHANGED",
                        "$.intended_use.prohibited_uses",
                    )
                )
    return sorted(issues, key=lambda item: (item.path, item.code))


def validate_package_structure(
    documents: dict[str, dict[str, Any]]
) -> list[Issue]:
    """Validate all package documents and prefix paths with document types."""

    issues: list[Issue] = []
    for expected_type in TEMPLATE_FILES:
        document = documents.get(expected_type)
        if document is None:
            issues.append(Issue("PACKAGE_DOCUMENT_MISSING", expected_type))
            continue
        for issue in validate_document(document, expected_type):
            issues.append(
                Issue(
                    issue.code,
                    f"{expected_type}:{issue.path}",
                    issue.level,
                )
            )
    return sorted(issues, key=lambda item: (item.path, item.code))


def has_errors(issues: Iterable[Issue]) -> bool:
    return any(issue.level == "error" for issue in issues)


def report_payload(
    check: str,
    issues: Iterable[Issue],
    *,
    counts: dict[str, int] | None = None,
    extra: dict[str, Any] | None = None,
) -> dict[str, Any]:
    issue_list = list(issues)
    payload: dict[str, Any] = {
        "check": check,
        "status": "fail" if has_errors(issue_list) else "pass",
        "issues": [item.as_dict() for item in issue_list],
        "counts": counts or {},
        "notice": NOTICE,
        "determinations_not_made": [
            "clinical_correctness",
            "clinical_safety",
            "diagnosis",
            "therapy_or_medication_selection",
            "dose_or_schedule",
            "interaction_or_contraindication",
            "triage_or_emergency_status",
            "prognosis",
            "privacy_or_legal_compliance",
        ],
    }
    if extra:
        payload.update(extra)
    return payload


def error_report(check: str, error: ValidationError) -> dict[str, Any]:
    return report_payload(check, [Issue(error.code, error.path)])


def print_report(report: dict[str, Any]) -> None:
    print(json.dumps(report, indent=2, sort_keys=True, ensure_ascii=False))


def atomic_write_json(destination: Path, payload: dict[str, Any]) -> Path:
    """Write private JSON atomically without implicit overwrite."""

    if destination.exists() or destination.is_symlink():
        raise ValidationError("OUTPUT_ALREADY_EXISTS", destination.name)
    temporary_name: str | None = None
    try:
        with tempfile.NamedTemporaryFile(
            "w",
            encoding="utf-8",
            dir=destination.parent,
            prefix=f".{destination.name}.",
            suffix=".tmp",
            delete=False,
        ) as handle:
            temporary_name = handle.name
            json.dump(
                payload,
                handle,
                indent=2,
                sort_keys=True,
                ensure_ascii=False,
            )
            handle.write("\n")
            handle.flush()
            os.fsync(handle.fileno())
        os.chmod(temporary_name, 0o600)
        # Publish a completed file without replacing a path created by another
        # writer after the initial existence check. Fail on filesystems without
        # hard-link support rather than fall back to a clobbering rename.
        os.link(temporary_name, destination)
        Path(temporary_name).unlink()
        return destination
    except FileExistsError as exc:
        raise ValidationError("OUTPUT_ALREADY_EXISTS", destination.name) from exc
    except OSError as exc:
        raise ValidationError("OUTPUT_WRITE_FAILED", destination.name) from exc
    finally:
        if temporary_name:
            try:
                Path(temporary_name).unlink(missing_ok=True)
            except OSError:
                pass


def copy_template_document(
    template_path: Path,
    *,
    subject_ref: str,
    classification: str,
) -> dict[str, Any]:
    document = read_json(template_path)
    document["subject_ref"] = subject_ref
    document["data_classification"] = classification
    if document.get("document_type") == "intended_use_handoff_record":
        privacy = document.get("privacy_process")
        if isinstance(privacy, dict):
            privacy["data_classification"] = classification
    return document


def direct_identifier_key_paths(
    value: Any, path: str = "$"
) -> list[str]:
    """Return paths for obvious direct-identifier field names, not values."""

    matches: list[str] = []
    if isinstance(value, dict):
        for key, nested in value.items():
            normalized = str(key).strip().lower()
            nested_path = f"{path}.{key}"
            if normalized in DIRECT_IDENTIFIER_KEYS:
                matches.append(nested_path)
            matches.extend(direct_identifier_key_paths(nested, nested_path))
    elif isinstance(value, list):
        for index, nested in enumerate(value):
            matches.extend(
                direct_identifier_key_paths(nested, f"{path}[{index}]")
            )
    return matches


def all_fact_references(
    documents: dict[str, dict[str, Any]]
) -> list[tuple[str, str]]:
    """Collect every source-fact reference with a nonclinical field path."""

    references: list[tuple[str, str]] = []

    def collect(value: Any, path: str) -> None:
        if isinstance(value, dict):
            for key, nested in value.items():
                nested_path = f"{path}.{key}"
                if key.endswith("fact_ids") and isinstance(nested, list):
                    for index, identifier in enumerate(nested):
                        if isinstance(identifier, str):
                            references.append(
                                (f"{nested_path}[{index}]", identifier)
                            )
                else:
                    collect(nested, nested_path)
        elif isinstance(value, list):
            for index, nested in enumerate(value):
                collect(nested, f"{path}[{index}]")

    for document_type, document in documents.items():
        if document_type != "source_fact_manifest":
            collect(document, document_type)
    return references


def record_ids(
    document: dict[str, Any],
    list_field: str,
    id_field: str,
) -> set[str]:
    records = document.get(list_field)
    if not isinstance(records, list):
        return set()
    return {
        record[id_field]
        for record in records
        if isinstance(record, dict) and isinstance(record.get(id_field), str)
    }
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall