mednotes-opencode 0.1.0

package/.opencode/mednotes/src/mednotes/domains/wiki/common.py

@@ -0,0 +1,69 @@
+"""Shared primitives for deterministic Wiki workflow operations."""
+from __future__ import annotations
+
+import json
+import shlex
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+# Generic exit codes + the MedOpsError hierarchy live in the framework; the
+# linker-specific code is domain-owned so the shared kernel stays product-free.
+from mednotes.kernel.errors import (  # noqa: F401
+    EXIT_IO,
+    EXIT_MISSING,
+    EXIT_OK,
+    EXIT_USAGE,
+    EXIT_VALIDATION,
+    CollisionError,
+    FileWriteError,
+    MedOpsError,
+    MissingPathError,
+    ValidationError,
+)
+
+EXIT_LINKER = 6
+
+MIGRATION_PLAN_SCHEMA = "medical-notes-workbench.taxonomy-migration-plan.v1"
+MIGRATION_RECEIPT_SCHEMA = "medical-notes-workbench.taxonomy-migration-receipt.v1"
+SUBAGENT_PLAN_SCHEMA = "medical-notes-workbench.subagent-plan.v1"
+WIKI_HEALTH_FIX_SCHEMA = "medical-notes-workbench.wiki-health-fix.v1"
+BLOCKER_RESOLUTION_SCHEMA = "medical-notes-workbench.blocker-resolution.v1"
+NOTE_MERGE_PLAN_SCHEMA = "medical-notes-workbench.note-merge-plan.v1"
+NOTE_MERGE_APPLY_SCHEMA = "medical-notes-workbench.note-merge-apply.v1"
+
+
+# Exit codes and the MedOpsError hierarchy now live in mednotes.kernel.errors
+# (framework); re-exported above for the many domain callers of wiki.common.
+
+
+def _now_iso() -> str:
+    return datetime.now(UTC).replace(microsecond=0).isoformat()
+
+
+def _json(data: Any) -> None:
+    print(json.dumps(data, ensure_ascii=False, indent=2))
+
+
+def wiki_cli_base_command() -> str:
+    """Return an executable command for the current Wiki CLI entrypoint."""
+    shim = Path(__file__).resolve().parents[4] / "scripts" / "mednotes" / "wiki" / "cli.py"
+    return "uv run python " + shlex.quote(str(shim))
+
+
+def wiki_cli_command(*args: object) -> str:
+    return " ".join([wiki_cli_base_command(), *(shlex.quote(str(arg)) for arg in args)])
+
+
+# Forma RELATIVA-ao-checkout dos caminhos canônicos, para instruções voltadas ao
+# agent que mostram um caminho relativo (vs. o absoluto do wiki_cli_base_command
+# acima). Fonte única: ao reorganizar a árvore, atualize SÓ aqui.
+# Ver ADR-0001 regra 10 (layout macio).
+WIKI_CLI_RELPATH = "bundle/scripts/mednotes/wiki/cli.py"
+DOCS_RELPATH = "bundle/docs"
+SKILLS_RELPATH = "bundle/skills"
+
+
+def wiki_cli_relative_command(command: str = "") -> str:
+    """`uv run python <cli> <command>` relativo ao checkout, para instruções ao agent."""
+    return f"uv run python {WIKI_CLI_RELPATH} {command}".rstrip()

package/.opencode/mednotes/src/mednotes/domains/wiki/config.py

@@ -0,0 +1,210 @@
+"""Configuration and resolved path helpers for Wiki workflows."""
+from __future__ import annotations
+
+import argparse
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from pydantic import ValidationError as PydanticValidationError
+
+import mednotes.platform.paths as mednotes_paths_module
+from mednotes.domains.wiki.common import ValidationError
+from mednotes.domains.wiki.contracts.paths import PathResolutionResult, blocker_from_wiki_resolution
+from mednotes.kernel.base import JsonObject, JsonObjectAdapter
+from mednotes.platform.paths import (
+    WikiPathResolution,
+    config_encoding_warnings,
+    environment_preflight,
+    expand_path,
+    find_config,
+    read_toml,
+    resolve_raw_dir,
+    resolve_wiki_dir,
+    user_state_dir,
+)
+from mednotes.platform.user_config import MedNotesUserConfig, load_user_config
+
+DEFAULT_CATALOG_PATH = mednotes_paths_module.DEFAULT_CATALOG_PATH
+DEFAULT_RAW_DIR = mednotes_paths_module.DEFAULT_RAW_DIR
+DEFAULT_WIKI_DIR = ""
+DEFAULT_VOCABULARY_DB_PATH = "~/.mednotes/vocabulary.sqlite"
+
+
+@dataclass(frozen=True)
+class MedConfig:
+    raw_dir: Path
+    wiki_dir: Path
+    catalog_path: Path
+    vocabulary_db_path: Path | None = None
+    artifact_dir: Path | None = None
+    state_dir: Path | None = None
+    wiki_source: str = ""
+    wiki_compat_warnings: tuple[str, ...] = ()
+    wiki_memory_path: Path | None = None
+    config_path: Path | None = None
+    user_config: MedNotesUserConfig = field(default_factory=MedNotesUserConfig)
+
+
+def _path(value: str | os.PathLike[str]) -> Path:
+    return expand_path(value)
+
+
+class WikiPathResolutionError(ValidationError):
+    """Raised when wiki_dir cannot be resolved safely before a workflow."""
+
+    def __init__(self, resolution: WikiPathResolution):
+        self.resolution = resolution
+        super().__init__(resolution.next_action or resolution.blocked_reason)
+
+    def payload(self, *, phase: str = "resolve_wiki_dir") -> dict[str, object]:
+        resolution_payload = self.resolution.as_payload(phase=phase)
+        blocker = blocker_from_wiki_resolution(resolution_payload)
+        result = PathResolutionResult(status="blocked", blocker=blocker)
+        return {
+            **resolution_payload,
+            **result.model_dump(mode="json")["blocker"],
+            "status": "blocked",
+        }
+
+
+def _user_state_dir() -> Path:
+    return user_state_dir()
+
+
+def _default_catalog_path() -> Path:
+    return user_state_dir() / "CATALOGO_WIKI.json"
+
+
+def _json_field(payload: JsonObject, key: str) -> object:
+    if key not in payload:
+        return None
+    return payload[key]
+
+
+def _json_str_field(payload: JsonObject, key: str) -> str:
+    value = _json_field(payload, key)
+    return value if isinstance(value, str) else ""
+
+
+def _json_list_field(payload: JsonObject, key: str) -> list[object]:
+    value = _json_field(payload, key)
+    return value if isinstance(value, list) else []
+
+
+def _json_object_field(payload: JsonObject, key: str) -> JsonObject:
+    value = _json_field(payload, key)
+    return JsonObjectAdapter.validate_python(value) if isinstance(value, dict) else {}
+
+
+def _read_toml(path: Path | None) -> JsonObject:
+    try:
+        return JsonObjectAdapter.validate_python(read_toml(path))
+    except RuntimeError as exc:
+        raise ValidationError(str(exc)) from exc
+
+
+def _load_user_config(path: Path | None) -> MedNotesUserConfig:
+    try:
+        return load_user_config(path)
+    except (OSError, tomllib.TOMLDecodeError, PydanticValidationError) as exc:
+        raise ValidationError(f"invalid MedNotes config: {exc}") from exc
+
+
+def _find_config(explicit: str | None) -> Path | None:
+    return find_config(explicit, start=Path.cwd())
+
+
+def resolve_config(args: argparse.Namespace) -> MedConfig:
+    explicit_config = getattr(args, "config", None)
+    config_path = _find_config(explicit_config)
+    user_config = _load_user_config(config_path)
+    cfg = _read_toml(config_path)
+    section = _json_object_field(cfg, "chat_processor")
+
+    def pick(name: str, env: str, default: str | os.PathLike[str]) -> Path:
+        cli_value = getattr(args, name, None)
+        value = cli_value or os.getenv(env) or _json_field(section, name) or default
+        return _path(str(value))
+
+    def pick_optional(name: str, env: str) -> Path | None:
+        cli_value = getattr(args, name, None)
+        value = cli_value or os.getenv(env) or _json_field(section, name)
+        return _path(str(value)) if value else None
+
+    vocabulary_value = (
+        getattr(args, "vocabulary_db", None)
+        or os.getenv("MEDNOTES_VOCABULARY_DB")
+        or _json_field(section, "vocabulary_db_path")
+        or _json_field(section, "vocabulary_db")
+    )
+    vocabulary_db_path = _path(str(vocabulary_value)) if vocabulary_value else user_state_dir() / "vocabulary.sqlite"
+
+    wiki_resolution = resolve_wiki_dir(
+        explicit=getattr(args, "wiki_dir", None),
+        config=explicit_config,
+        start=Path.cwd(),
+        enable_gemini_probe=False,
+    )
+    if not wiki_resolution.ok:
+        raise WikiPathResolutionError(wiki_resolution)
+    wiki_dir = wiki_resolution.path
+    if wiki_dir is None:
+        raise WikiPathResolutionError(wiki_resolution)
+
+    return MedConfig(
+        raw_dir=resolve_raw_dir(
+            explicit=getattr(args, "raw_dir", None),
+            config=explicit_config,
+            start=Path.cwd(),
+        ),
+        wiki_dir=wiki_dir,
+        catalog_path=pick("catalog_path", "MED_CATALOG_PATH", _default_catalog_path()),
+        vocabulary_db_path=vocabulary_db_path,
+        artifact_dir=pick_optional("artifact_dir", "MED_ARTIFACT_DIR"),
+        state_dir=user_state_dir(),
+        wiki_source=wiki_resolution.source,
+        wiki_compat_warnings=wiki_resolution.compat_warnings,
+        wiki_memory_path=wiki_resolution.memory_path,
+        config_path=config_path,
+        user_config=user_config,
+    )
+
+
+def validate_config(config: MedConfig) -> JsonObject:
+    preflight = environment_preflight(
+        extension_root=Path(__file__).resolve().parents[4],
+        state_dir=config.state_dir or user_state_dir(),
+        sample_paths=[
+            config.raw_dir,
+            config.wiki_dir,
+            config.catalog_path,
+            *( [config.vocabulary_db_path] if config.vocabulary_db_path else [] ),
+        ],
+    )
+    preflight_payload = JsonObjectAdapter.validate_python(preflight)
+    return {
+        "phase": "validate_environment",
+        "status": _json_str_field(preflight_payload, "status") or "completed",
+        "blocked_reason": _json_str_field(preflight_payload, "blocked_reason"),
+        "next_action": _json_str_field(preflight_payload, "next_action"),
+        "required_inputs": _json_list_field(preflight_payload, "required_inputs"),
+        "human_decision_required": False,
+        "raw_dir": str(config.raw_dir),
+        "raw_dir_exists": config.raw_dir.exists(),
+        "wiki_dir": str(config.wiki_dir),
+        "wiki_dir_exists": config.wiki_dir.exists(),
+        "wiki_source": config.wiki_source,
+        "wiki_memory_path": str(config.wiki_memory_path) if config.wiki_memory_path else "",
+        "config_path": str(config.config_path) if config.config_path else "",
+        "config_encoding_warnings": config_encoding_warnings(config.config_path),
+        "wiki_compat_warnings": list(config.wiki_compat_warnings),
+        "catalog_path": str(config.catalog_path),
+        "catalog_path_exists": config.catalog_path.exists(),
+        "vocabulary_db_path": str(config.vocabulary_db_path) if config.vocabulary_db_path else "",
+        "vocabulary_db_exists": bool(config.vocabulary_db_path and config.vocabulary_db_path.exists()),
+        "artifact_dir": str(config.artifact_dir) if config.artifact_dir else "",
+        "artifact_dir_exists": bool(config.artifact_dir and config.artifact_dir.exists()),
+        "environment_preflight": preflight,
+    }

package/.opencode/mednotes/src/mednotes/domains/wiki/contracts/__init__.py

@@ -0,0 +1,74 @@
+"""Executable contract models for Medical Notes Workbench workflows."""
+
+from mednotes.kernel.base import ContractModel, contract_error
+from mednotes.kernel.blockers import BlockerEntryModel
+from mednotes.kernel.progress import (
+    ProgressMode,
+    WorkflowProgressCounts,
+    WorkflowProgressEvent,
+    WorkflowProgressEventType,
+    WorkflowProgressState,
+    WorkflowProgressStatus,
+    WorkflowProgressViewModel,
+    build_progress_view_model,
+    fold_progress_events,
+)
+from mednotes.kernel.state_machine import (
+    WorkflowStateCategory,
+    WorkflowStateMachineSnapshot,
+    WorkflowTransition,
+)
+from mednotes.kernel.workflow import (
+    AutomationKind,
+    DecisionEvidence,
+    DecisionKind,
+    HumanDecisionOption,
+    HumanDecisionPacket,
+    ReceiptStatus,
+    RejectedAutomation,
+    VersionControlSafety,
+    WorkflowArtifact,
+    WorkflowAutomationKind,
+    WorkflowDecision,
+    WorkflowDecisionKind,
+    WorkflowOutcomeError,
+    WorkflowPhaseOutcome,
+    WorkflowPhaseReceipt,
+    WorkflowReceiptPayload,
+    WorkflowRollback,
+)
+
+__all__ = [
+    "AutomationKind",
+    "BlockerEntryModel",
+    "ContractModel",
+    "DecisionEvidence",
+    "DecisionKind",
+    "HumanDecisionOption",
+    "HumanDecisionPacket",
+    "ProgressMode",
+    "ReceiptStatus",
+    "RejectedAutomation",
+    "VersionControlSafety",
+    "WorkflowAutomationKind",
+    "WorkflowArtifact",
+    "WorkflowDecision",
+    "WorkflowDecisionKind",
+    "WorkflowOutcomeError",
+    "WorkflowPhaseOutcome",
+    "WorkflowPhaseReceipt",
+    "WorkflowProgressCounts",
+    "WorkflowProgressEvent",
+    "WorkflowProgressEventType",
+    "WorkflowProgressState",
+    "WorkflowProgressStatus",
+    "WorkflowProgressViewModel",
+    "WorkflowReceiptPayload",
+    "WorkflowRollback",
+    "WorkflowStateCategory",
+    "WorkflowStateMachineSnapshot",
+    "WorkflowTransition",
+    "build_progress_view_model",
+    "contract_error",
+    "fold_progress_events",
+]

package/.opencode/mednotes/src/mednotes/domains/wiki/contracts/agent_report.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import Field, field_validator, model_validator
+from pydantic_core.core_schema import ValidationInfo
+
+from mednotes.domains.wiki.contracts.agent_run_audit import WorkflowTranscriptAuditResult
+from mednotes.domains.wiki.contracts.happy_path import HappyPathRunMetrics
+from mednotes.domains.wiki.contracts.public_report import WorkflowPublicReportViewModel
+from mednotes.kernel.base import ContractModel, JsonObject
+from mednotes.kernel.public_report import WorkflowPrimaryObjectiveSummary
+
+
+class AgentRunReportFindingCode(StrEnum):
+    RECEIPT_STATUS_MISMATCH = "agent.final_report_receipt_status_mismatch"
+    PROGRESS_STATUS_MISMATCH = "agent.final_report_progress_status_mismatch"
+    WORKFLOW_STATUS_OMITTED = "agent.final_report_workflow_status_omitted"
+    OMITTED_TOOL_ERROR = "agent.final_report_omitted_tool_error"
+    REPORTED_ARTIFACT_PATH_INVALID = "agent.final_report_artifact_path_invalid"
+    FINAL_REPORT_LOCAL_PATH_LEAK = "agent.final_report_local_path_leak"
+    SUCCESS_CLAIM_MISMATCH = "agent.final_report_success_claim_mismatch"
+    PUBLIC_OUTPUT_INTERNAL_TERM_LEAK = "agent.public_output_internal_term_leak"
+    STALE_NEXT_ACTION = "agent.workflow_stale_next_action"
+    PRIMARY_OBJECTIVE_OMITTED = "agent.final_report_primary_objective_omitted"
+    TOOL_DEVIATION_OMITTED = "agent.final_report_tool_deviation_omitted"
+    WORKFLOW_CONTRACT_CONTRADICTION = "agent.workflow_contract_contradiction"
+    AGENT_EVENT_OMITTED = "agent.final_report_agent_event_omitted"
+    VERSION_CONTROL_SAFETY_OMITTED = "agent.final_report_version_control_safety_omitted"
+    API_ACCOUNTING_MISMATCH = "agent.final_report_api_accounting_mismatch"
+    OPERATIONAL_WARNING_OMITTED = "agent.final_report_operational_warning_omitted"
+    WAITING_AGENT_CONTINUATION_OMITTED = "agent.final_report_waiting_agent_continuation_omitted"
+    FINAL_REPORT_NOT_ALLOWED = "agent.final_report_not_allowed"
+    WORKFLOW_AGENT_DIRECTIVE_INVALID = "agent.workflow_agent_directive_invalid"
+    MISSING_ERROR_CONTEXT_ROOT_CAUSE = "agent.final_report_missing_error_context_root_cause"
+    CONTENT_QUALITY_AUDIT_OMITTED = "agent.final_report_content_quality_audit_omitted"
+    RUNTIME_ERROR_OMITTED = "agent.final_report_runtime_error_omitted"
+    RUNTIME_PERFORMANCE_BUG = "agent.runtime_performance_bug"
+    RUNTIME_ROUTE_PROBE_OBSERVED = "agent.runtime_route_probe_observed"
+    SPECIALIST_MODEL_POLICY_VIOLATION = "agent.specialist_model_policy_violation"
+    BLOCKED_TOOL_RESULT_OMITTED = "agent.final_report_blocked_tool_result_omitted"
+    RUN_FINISH_OMITTED = "agent.final_report_run_finish_omitted"
+    FINAL_REPORT_INCOMPLETE = "agent.final_report_incomplete"
+    WAITING_EXTERNAL_CONTINUATION_ATTEMPTED = "agent.waiting_external_continuation_attempted"
+    BATCH_PROGRESS_REPORT_OMITTED = "agent.batch_progress_report_omitted"
+    SPECIALIST_APPLY_STEP_OMITTED = "agent.specialist_apply_step_omitted"
+    SPECIALIST_REWRITE_COUNT_MISMATCH = "agent.final_report_specialist_rewrite_count_mismatch"
+    READY_CONTINUATION_STOPPED = "agent.ready_continuation_stopped"
+    PROCESS_CHATS_PRIMARY_OBJECTIVE_UNRESOLVED = "agent.process_chats_primary_objective_unresolved"
+    PROCESS_CHATS_VAULT_DELETION_WITHOUT_RECEIPT = "agent.process_chats_vault_deletion_without_receipt"
+    TRANSCRIPT_UNREADABLE = "agent.transcript_unreadable"
+    SUBAGENT_RAW_CONTENT_CONTRACT_VIOLATION = "agent.subagent_raw_content_contract_violation"
+    PARENT_CANONICAL_ARTIFACT_WRITE_BEFORE_SUBAGENT = "agent.parent_canonical_artifact_write_before_subagent"
+    PARENT_CANONICAL_ARTIFACT_WRITE_AFTER_SUBAGENT = "agent.parent_canonical_artifact_write_after_subagent"
+    PARALLEL_HUMAN_DECISION_BACKLOG = "agent.parallel_human_decision_backlog"
+    AGY_MATERIALIZED_SKILL_MISCLASSIFIED_AS_STALE = "agent.agy_materialized_skill_misclassified_as_stale"
+    RECOVERABLE_TOOL_ERROR_OBSERVED = "agent.recoverable_tool_error_observed"
+    EFFECT_PAYLOAD_CONTRACT_INVALID = "effect_payload_contract_invalid"
+
+
+AgentRunReportSeverity = Literal["low", "medium", "high", "critical"]
+AgentRunReportValidationStatus = Literal["completed", "blocked"]
+FixWikiObjectiveStatus = Literal["yes", "partial", "no", "waiting_agent", "waiting_external", "failed", "unknown"]
+FixWikiGraphStatus = Literal["improved", "clean", "blocked", "unchanged", "worse", "unknown"]
+FixWikiRelatedNotesStatus = Literal["updated", "pending", "blocked", "skipped", "unknown"]
+ProcessChatsObjectiveStatus = Literal[
+    "no_pending",
+    "preview_ready",
+    "ready_to_publish",
+    "published",
+    "completed_with_link_blockers",
+    "completed",
+    "blocked",
+    "failed",
+    "unknown",
+]
+ProcessChatsNotesStatus = Literal["ready_to_publish", "published", "not_written", "blocked", "unknown"]
+ProcessChatsRawStatus = Literal["covered", "processed", "partial", "not_processed", "unknown"]
+ProcessChatsCoverageStatus = Literal["valid", "missing", "invalid", "not_applicable", "unknown"]
+ProcessChatsLinkerStatus = Literal["applied", "blocked", "skipped", "not_run", "not_applicable", "unknown"]
+StyleRewriteApplyStatus = Literal["applied", "completed", "blocked", "failed", "waiting_external"]
+
+
+class StyleRewriteAtomicApplyItem(ContractModel):
+    """Typed item evidence emitted by style-rewrite apply tools."""
+
+    work_id: str = ""
+    written: bool
+
+
+class StyleRewriteAtomicApplyResult(ContractModel):
+    """Tool-output contract consumed by final report validation."""
+
+    schema_: Literal[
+        "medical-notes-workbench.style-rewrite-atomic-apply-agent-stdout.v1",
+        "medical-notes-workbench.style-rewrite-atomic-apply-result.v1",
+    ] = Field(alias="schema")
+    status: StyleRewriteApplyStatus
+    work_id: str = ""
+    written_count: int = Field(default=0, ge=0)
+    items: tuple[StyleRewriteAtomicApplyItem, ...] = ()
+
+
+class FixWikiPrimaryObjectiveSummary(ContractModel):
+    schema_: Literal["medical-notes-workbench.fix-wiki-primary-objective-summary.v1"] = Field(
+        "medical-notes-workbench.fix-wiki-primary-objective-summary.v1",
+        alias="schema",
+    )
+    wiki_fixed: FixWikiObjectiveStatus
+    wiki_summary: str
+    mutation_count: int = Field(ge=0)
+    written_count: int = Field(ge=0)
+    mutation_summary: str
+    graph_status: FixWikiGraphStatus
+    graph_summary: str
+    related_notes_status: FixWikiRelatedNotesStatus
+    related_notes_summary: str
+    required_report_items: list[str] = Field(
+        default_factory=lambda: [
+            "wiki_fixed",
+            "mutation_summary",
+            "graph_summary",
+            "related_notes_summary",
+        ]
+    )
+
+    @field_validator("wiki_summary", "mutation_summary", "graph_summary", "related_notes_summary")
+    @classmethod
+    def _required_summary_text(cls, value: str, info: ValidationInfo) -> str:
+        cleaned = value.strip()
+        if not cleaned:
+            raise ValueError(f"{info.field_name} must be non-empty")
+        return cleaned
+
+
+class ProcessChatsPrimaryObjectiveSummary(ContractModel):
+    schema_: Literal["medical-notes-workbench.process-chats-primary-objective-summary.v1"] = Field(
+        "medical-notes-workbench.process-chats-primary-objective-summary.v1",
+        alias="schema",
+    )
+    process_status: ProcessChatsObjectiveStatus
+    process_summary: str
+    notes_status: ProcessChatsNotesStatus
+    note_count: int = Field(ge=0, strict=True)
+    wiki_write_summary: str
+    raw_status: ProcessChatsRawStatus
+    raw_count: int = Field(ge=0, strict=True)
+    raw_summary: str
+    coverage_status: ProcessChatsCoverageStatus
+    coverage_summary: str
+    linker_status: ProcessChatsLinkerStatus
+    linker_summary: str
+    required_report_items: list[str] = Field(
+        default_factory=lambda: [
+            "process_status",
+            "raw_summary",
+            "wiki_write_summary",
+            "coverage_summary",
+            "linker_summary",
+        ]
+    )
+
+    @field_validator(
+        "process_summary",
+        "wiki_write_summary",
+        "raw_summary",
+        "coverage_summary",
+        "linker_summary",
+    )
+    @classmethod
+    def _required_summary_text(cls, value: str, info: ValidationInfo) -> str:
+        cleaned = value.strip()
+        if not cleaned:
+            raise ValueError(f"{info.field_name} must be non-empty")
+        return cleaned
+
+
+class AgentRunReportFinding(ContractModel):
+    schema_: Literal["medical-notes-workbench.agent-run-report-finding.v1"] = Field(
+        "medical-notes-workbench.agent-run-report-finding.v1",
+        alias="schema",
+    )
+    code: AgentRunReportFindingCode
+    severity: AgentRunReportSeverity
+    source: str
+    message: str
+    next_action: str
+    source_field: str = ""
+    expected: str = ""
+    actual: str = ""
+    path: str = ""
+    artifact_name: str = ""
+    tool_error_type: str = ""
+    evidence: JsonObject = Field(default_factory=dict)
+
+    @field_validator("source", "message", "next_action")
+    @classmethod
+    def _required_text(cls, value: str, info: ValidationInfo) -> str:
+        cleaned = value.strip()
+        if not cleaned:
+            raise ValueError(f"{info.field_name} must be non-empty")
+        return cleaned
+
+
+class AgentRunReportValidation(ContractModel):
+    schema_: Literal["medical-notes-workbench.agent-run-report-validation.v1"] = Field(
+        "medical-notes-workbench.agent-run-report-validation.v1",
+        alias="schema",
+    )
+    phase: Literal["validate_agent_run_report"] = "validate_agent_run_report"
+    status: AgentRunReportValidationStatus
+    workflow: str = ""
+    run_id: str = ""
+    workflow_status: str = ""
+    workflow_phase: str = ""
+    receipt_status: str = ""
+    blocked_reason: str = ""
+    next_action: str = ""
+    final_report_present: bool = False
+    transcript_present: bool = False
+    workflow_payload_path: str = ""
+    transcript_path: str = ""
+    final_report_path: str = ""
+    primary_objective: (
+        FixWikiPrimaryObjectiveSummary | ProcessChatsPrimaryObjectiveSummary | WorkflowPrimaryObjectiveSummary | None
+    ) = None
+    happy_path_metrics: HappyPathRunMetrics | None = None
+    public_report_view_model: WorkflowPublicReportViewModel | None = None
+    transcript_audit: WorkflowTranscriptAuditResult | None = None
+    finding_count: int = Field(ge=0)
+    findings: list[AgentRunReportFinding] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _validate_report_contract(self) -> AgentRunReportValidation:
+        if self.finding_count != len(self.findings):
+            raise ValueError("finding_count must match findings length")
+        if self.findings and self.status != "blocked":
+            raise ValueError("findings require blocked status")
+        if self.status == "blocked" and not self.next_action.strip():
+            raise ValueError("blocked validation requires next_action")
+        return self