mednotes-opencode 0.1.0

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

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import ConfigDict, Field, model_validator
+
+from mednotes.kernel.base import ContractModel, JsonObject
+
+
+class HappyPathViolationCategory(StrEnum):
+    ROUTE = "route"
+    TOOL_CONTRACT = "tool_contract"
+    FSM_CONTRACT = "fsm_contract"
+    ARTIFACT_INTEGRITY = "artifact_integrity"
+    PUBLIC_COMMUNICATION = "public_communication"
+    PERFORMANCE = "performance"
+    PRIMARY_OBJECTIVE = "primary_objective"
+    HUMAN_ATTENTION = "human_attention"
+
+
+class HappyPathViolation(ContractModel):
+    code: str = Field(min_length=1)
+    category: HappyPathViolationCategory
+    severity: Literal["low", "medium", "high", "critical"]
+    message: str = Field(min_length=1)
+    evidence: JsonObject = Field(default_factory=dict)
+
+
+class HappyPathFindingInput(ContractModel):
+    # Agent report findings carry richer audit fields; happy-path scoring only
+    # consumes the stable violation surface below.
+    model_config = ConfigDict(extra="ignore", populate_by_name=True, validate_assignment=True)
+
+    code: str = Field(min_length=1)
+    severity: Literal["low", "medium", "high", "critical"]
+    message: str = Field(min_length=1)
+    evidence: JsonObject = Field(default_factory=dict)
+
+
+class HappyPathRunMetrics(ContractModel):
+    schema_: Literal["medical-notes-workbench.happy-path-run-metrics.v1"] = Field(
+        "medical-notes-workbench.happy-path-run-metrics.v1",
+        alias="schema",
+    )
+    workflow: str = Field(min_length=1)
+    run_id: str = Field(min_length=1)
+    status: Literal["happy", "degraded", "failed"]
+    score: int = Field(ge=0, le=100)
+    primary_objective_completed: bool
+    legitimate_stop_reason: str = ""
+    violation_count: int = Field(ge=0)
+    violations: list[HappyPathViolation] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _count_and_score_match(self) -> HappyPathRunMetrics:
+        if self.violation_count != len(self.violations):
+            raise ValueError("violation_count must match violations length")
+        if self.violation_count == 0 and self.score != 100:
+            raise ValueError("perfect happy path must score 100")
+        if self.status == "happy" and self.violation_count != 0:
+            raise ValueError("happy status cannot include violations")
+        return self
+
+
+class HappyPathRoundMetrics(ContractModel):
+    schema_: Literal["medical-notes-workbench.happy-path-round-metrics.v1"] = Field(
+        "medical-notes-workbench.happy-path-round-metrics.v1",
+        alias="schema",
+    )
+    workflow: str = Field(min_length=1)
+    run_count: int = Field(ge=0)
+    happy_run_count: int = Field(ge=0)
+    happy_path_prevalence_percent: int = Field(ge=0, le=100)
+    target_prevalence_percent: int = 100
+    runs: list[HappyPathRunMetrics] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _round_counts_match_runs(self) -> HappyPathRoundMetrics:
+        if self.run_count != len(self.runs):
+            raise ValueError("run_count must match runs length")
+        if self.happy_run_count != sum(1 for run in self.runs if run.status == "happy"):
+            raise ValueError("happy_run_count must match happy runs")
+        expected = 100 if self.run_count == 0 else int((self.happy_run_count / self.run_count) * 100)
+        if self.happy_path_prevalence_percent != expected:
+            raise ValueError("happy_path_prevalence_percent must match run counts")
+        return self
+
+
+_FINDING_CATEGORY_BY_CODE: dict[str, HappyPathViolationCategory] = {
+    "agent.public_output_internal_term_leak": HappyPathViolationCategory.PUBLIC_COMMUNICATION,
+    "agent.final_report_success_claim_mismatch": HappyPathViolationCategory.PUBLIC_COMMUNICATION,
+    "agent.final_report_progress_status_mismatch": HappyPathViolationCategory.FSM_CONTRACT,
+    "agent.final_report_receipt_status_mismatch": HappyPathViolationCategory.FSM_CONTRACT,
+    "agent.workflow_contract_contradiction": HappyPathViolationCategory.FSM_CONTRACT,
+    "agent.final_report_tool_deviation_omitted": HappyPathViolationCategory.ROUTE,
+    "agent.runtime_route_probe_observed": HappyPathViolationCategory.ROUTE,
+    "agent.waiting_external_continuation_attempted": HappyPathViolationCategory.ROUTE,
+    "agent.ready_continuation_stopped": HappyPathViolationCategory.ROUTE,
+    "agent.runtime_performance_bug": HappyPathViolationCategory.PERFORMANCE,
+    "agent.final_report_primary_objective_omitted": HappyPathViolationCategory.PRIMARY_OBJECTIVE,
+    "agent.process_chats_primary_objective_unresolved": HappyPathViolationCategory.PRIMARY_OBJECTIVE,
+    "agent.process_chats_vault_deletion_without_receipt": HappyPathViolationCategory.ARTIFACT_INTEGRITY,
+    "agent.specialist_model_policy_violation": HappyPathViolationCategory.ROUTE,
+}
+
+
+def happy_path_metrics_from_findings(
+    *,
+    workflow: str,
+    run_id: str,
+    findings: Sequence[object],
+    primary_objective_completed: bool,
+    legitimate_stop_reason: str,
+) -> HappyPathRunMetrics:
+    violations = [_violation_from_finding(finding) for finding in findings]
+    if not primary_objective_completed and not legitimate_stop_reason:
+        violations.append(
+            HappyPathViolation(
+                code="workflow.primary_objective_not_completed",
+                category=HappyPathViolationCategory.PRIMARY_OBJECTIVE,
+                severity="high",
+                message="Workflow did not complete its declared primary objective.",
+            )
+        )
+    score = max(0, 100 - sum(_severity_penalty(item.severity) for item in violations))
+    status: Literal["happy", "degraded", "failed"]
+    if not violations:
+        status = "happy"
+    elif any(item.severity in {"high", "critical"} for item in violations):
+        status = "failed"
+    else:
+        status = "degraded"
+    return HappyPathRunMetrics(
+        workflow=workflow,
+        run_id=run_id,
+        status=status,
+        score=score,
+        primary_objective_completed=primary_objective_completed,
+        legitimate_stop_reason=legitimate_stop_reason,
+        violation_count=len(violations),
+        violations=violations,
+    )
+
+
+def happy_path_round_metrics(*, workflow: str, runs: list[HappyPathRunMetrics]) -> HappyPathRoundMetrics:
+    happy_run_count = sum(1 for run in runs if run.status == "happy")
+    run_count = len(runs)
+    prevalence = 100 if run_count == 0 else int((happy_run_count / run_count) * 100)
+    return HappyPathRoundMetrics(
+        workflow=workflow,
+        run_count=run_count,
+        happy_run_count=happy_run_count,
+        happy_path_prevalence_percent=prevalence,
+        runs=runs,
+    )
+
+
+def _violation_from_finding(finding: object) -> HappyPathViolation:
+    typed = _finding_input(finding)
+    return HappyPathViolation(
+        code=typed.code,
+        category=_FINDING_CATEGORY_BY_CODE.get(typed.code, HappyPathViolationCategory.ROUTE),
+        severity=typed.severity,
+        message=typed.message,
+        evidence=typed.evidence,
+    )
+
+
+def _finding_input(finding: object) -> HappyPathFindingInput:
+    if isinstance(finding, HappyPathFindingInput):
+        return finding
+    if isinstance(finding, ContractModel):
+        return HappyPathFindingInput.model_validate(finding.to_payload())
+    return HappyPathFindingInput.model_validate(finding)
+
+
+def _severity_penalty(severity: str) -> int:
+    match severity:
+        case "critical":
+            return 100
+        case "high":
+            return 50
+        case "medium":
+            return 25
+        case "low":
+            return 10
+        case _:
+            return 25

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

@@ -0,0 +1,110 @@
+"""Typed Git/linker state contracts.
+
+Git status, worktree diffs and persisted link-state JSON are external adapter
+inputs. These models are the first trusted shape before link diagnosis decides
+trigger context, stale diagnosis or redundant blocked reruns.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from mednotes.kernel.base import ContractModel, JsonObject, JsonObjectAdapter
+
+LINK_GIT_CONTEXT_SCHEMA = "medical-notes-workbench.link-git-context.v1"
+LINK_STATE_SCHEMA = "medical-notes-workbench.link-state.v1"
+LINK_STATE_SCHEMA_V2 = "medical-notes-workbench.link-state.v2"
+GIT_TRIGGER_SOURCE = "/mednotes:link.git"
+
+GitChangeType = Literal["created", "modified", "deleted", "renamed", "moved"]
+
+
+def _without_empty_strings(payload: JsonObject) -> JsonObject:
+    """Keep public Git payloads compact while the internal model stays explicit."""
+
+    return JsonObjectAdapter.validate_python(
+        {key: value for key, value in payload.items() if value not in ("", None, [])}
+    )
+
+
+class LinkGitChangeEvent(ContractModel):
+    change_type: GitChangeType
+    content_change: str = ""
+    path: str = ""
+    old_path: str = ""
+    title: str = ""
+    old_title: str = ""
+    replacement_path: str = ""
+    replacement_title: str = ""
+    before_hash: str = ""
+    after_hash: str = ""
+
+    def to_payload(self) -> JsonObject:
+        return _without_empty_strings(super().to_payload())
+
+
+class LinkGitChangedPath(ContractModel):
+    change_type: GitChangeType
+    path: str = ""
+    old_path: str = ""
+
+    def to_payload(self) -> JsonObject:
+        return _without_empty_strings(super().to_payload())
+
+
+class LinkGitContext(ContractModel):
+    schema_id: Literal["medical-notes-workbench.link-git-context.v1"] = Field(alias="schema")
+    available: bool = Field(strict=True)
+    repo_root: str
+    branch: str
+    head: str
+    previous_link_head: str
+    dirty: bool = Field(strict=True)
+    changed_note_count: int = Field(ge=0, strict=True)
+    changed_notes: list[LinkGitChangeEvent] = Field(default_factory=list)
+    changed_paths: list[LinkGitChangedPath] = Field(default_factory=list)
+    trigger_context_available: bool = Field(strict=True)
+    status_hash: str
+    unavailable_reason: str = ""
+
+    def to_payload(self) -> JsonObject:
+        payload = super().to_payload()
+        if not self.unavailable_reason:
+            payload.pop("unavailable_reason", None)
+        payload["changed_notes"] = [event.to_payload() for event in self.changed_notes]
+        payload["changed_paths"] = [event.to_payload() for event in self.changed_paths]
+        return JsonObjectAdapter.validate_python(payload)
+
+
+class LinkTriggerContextFromGit(ContractModel):
+    schema_id: Literal["medical-notes-workbench.link-trigger-context.v1"] = Field(alias="schema")
+    source_workflow: Literal["/mednotes:link.git"]
+    changed_notes: list[LinkGitChangeEvent]
+    catalog_changed: bool = Field(default=False, strict=True)
+    related_notes_export_changed: bool = Field(default=False, strict=True)
+
+    def to_payload(self) -> JsonObject:
+        payload = super().to_payload()
+        payload["changed_notes"] = [event.to_payload() for event in self.changed_notes]
+        return JsonObjectAdapter.validate_python(payload)
+
+
+class LinkState(ContractModel):
+    schema_id: Literal[
+        "medical-notes-workbench.link-state.v1",
+        "medical-notes-workbench.link-state.v2",
+    ] = Field(alias="schema")
+    generated_at: str = ""
+    snapshot_hash: str = ""
+    git_head: str = ""
+    git_status_hash: str = ""
+    receipt_path: str = ""
+    last_diagnosis_attempt: JsonObject | None = None
+
+    def to_payload(self) -> JsonObject:
+        payload = super().to_payload()
+        if self.last_diagnosis_attempt is None:
+            payload.pop("last_diagnosis_attempt", None)
+        return JsonObjectAdapter.validate_python(payload)

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

@@ -0,0 +1,52 @@
+"""Canonical `/mednotes:link` artifact boundary for parent workflows.
+
+Lower-level link adapters may still translate raw runtime output, but a parent
+workflow can only consume the public child FSM payload. Accepting `link-run.v1`
+here would recreate a second source of workflow state.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import ConfigDict, Field
+
+from mednotes.kernel.base import ContractModel, JsonObject
+from mednotes.kernel.progress import WorkflowProgressViewModel
+
+
+class LinkFsmArtifact(ContractModel):
+    # Parent workflows consume a stable subset of the child FSM payload. The
+    # schema discriminator rejects legacy artifacts; extra fields are ignored so
+    # public child-FSM additions do not become a second parent-state contract.
+    model_config = ConfigDict(extra="ignore", strict=True)
+
+    schema_id: Literal["medical-notes-workbench.link-fsm-result.v1"] = Field(alias="schema")
+    workflow: Literal["/mednotes:link", "/mednotes:link-body"]
+    run_id: str = Field(min_length=1)
+    state_machine_snapshot: JsonObject
+    progress_view_model: WorkflowProgressViewModel
+    decision: JsonObject | None = None
+    human_decision_packet: JsonObject | None = None
+    receipt: JsonObject
+    reports: JsonObject
+    agent_directive: JsonObject
+    artifacts: JsonObject
+    version_control_safety: JsonObject
+    diagnostic_context: JsonObject | None = None
+    error_context: JsonObject
+
+    @property
+    def operation_status(self) -> str:
+        return self.progress_view_model.status.value
+
+
+def normalize_link_runtime_artifact(payload: object) -> LinkFsmArtifact:
+    """Validate the child FSM payload before its status can affect the parent."""
+
+    if not isinstance(payload, dict):
+        raise ValueError("link artifact must be an object")
+    schema = payload["schema"] if "schema" in payload else ""
+    if schema != "medical-notes-workbench.link-fsm-result.v1":
+        raise ValueError("link artifact must be medical-notes-workbench.link-fsm-result.v1")
+    return LinkFsmArtifact.model_validate(payload)

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

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field, model_validator
+
+from mednotes.domains.wiki.contracts.raw_coverage import (
+    CoverageAction as CoverageAction,
+)
+from mednotes.domains.wiki.contracts.raw_coverage import (
+    RawCoverage as RawCoverage,
+)
+from mednotes.domains.wiki.contracts.raw_coverage import (
+    RawCoverageItem as RawCoverageItem,
+)
+from mednotes.kernel.base import ContractModel
+
+PlanAction = Literal["planned_meaning", "attach_to_planned_meaning", "not_a_note", "needs_context"]
+
+
+class MeaningClaim(ContractModel):
+    label: str = Field(min_length=1)
+    scope: str = Field(min_length=1)
+    boundaries: list[str]
+    kind: Literal[
+        "clinical_concept",
+        "drug_concept",
+        "diagnostic_criterion",
+        "management_strategy",
+        "procedure",
+        "physiology_or_mechanism",
+        "epidemiology_or_definition",
+    ]
+    evidence_summary: str = Field(min_length=1)
+    id: str | None = None
+
+
+class TriageNotePlanItem(ContractModel):
+    id: str = Field(min_length=1)
+    action: PlanAction
+    title: str | None = None
+    staged_title: str | None = None
+    meaning_claim: MeaningClaim | None = None
+    taxonomy_hint: str | None = None
+    aliases: list[str] | None = None
+    target_item_id: str | None = None
+    reason_code: str | None = None
+    reason: str | None = None
+
+    @model_validator(mode="after")
+    def validate_action_payload(self) -> TriageNotePlanItem:
+        if self.action == "planned_meaning":
+            if not self.title or not self.staged_title or self.meaning_claim is None:
+                raise ValueError("planned_meaning items require title, staged_title and meaning_claim")
+        elif self.action == "attach_to_planned_meaning":
+            if not self.target_item_id or not self.reason_code or not self.reason:
+                raise ValueError("attach_to_planned_meaning items require target_item_id, reason_code and reason")
+        elif self.action in {"not_a_note", "needs_context"} and (not self.reason_code or not self.reason):
+            raise ValueError(f"{self.action} items require reason_code and reason")
+        return self
+
+
+class TriageNotePlan(ContractModel):
+    schema_id: Literal["medical-notes-workbench.triage-note-plan.v2"] = Field(alias="schema")
+    raw_file: str = Field(min_length=1)
+    exhaustive: Literal[True] = True
+    items: list[TriageNotePlanItem] = Field(min_length=1)
+    batch_id: str | None = None
+    run_id: str | None = None
+    source_artifact_hash: str | None = None
+
+
+# RawCoverage lives in raw_coverage.py because it is a publish boundary, not a
+# triage-plan concept. These imports remain as a stable public import path for
+# existing schema/test code while the implementation has a single source.

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

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import Field, field_validator, model_validator
+
+from mednotes.kernel.base import ContractModel, JsonObject
+
+PathBlockerReason = Literal[
+    "paths.wiki_dir_missing",
+    "paths.raw_dir_missing",
+    "paths.ambiguous",
+    "paths.config_invalid",
+]
+PathRequiredInput = Literal["wiki_dir", "raw_dir", "config_path"]
+_WIKI_REASON_MAP: dict[str, PathBlockerReason] = {
+    "missing_wiki_dir": "paths.wiki_dir_missing",
+    "ambiguous_wiki_dir": "paths.ambiguous",
+    "invalid_wiki_dir": "paths.config_invalid",
+}
+_DEFAULT_REASON: PathBlockerReason = "paths.config_invalid"
+
+
+class WorkbenchPathsConfig(ContractModel):
+    wiki_dir: Path
+    raw_dir: Path | None = None
+
+    @field_validator("wiki_dir")
+    @classmethod
+    def wiki_dir_must_exist(cls, value: Path) -> Path:
+        if not value.exists() or not value.is_dir():
+            raise ValueError("wiki_dir must be an existing directory")
+        return value
+
+    @field_validator("raw_dir")
+    @classmethod
+    def raw_dir_must_exist_when_present(cls, value: Path | None) -> Path | None:
+        if value is not None and (not value.exists() or not value.is_dir()):
+            raise ValueError("raw_dir must be an existing directory when provided")
+        return value
+
+
+class PathResolutionBlocker(ContractModel):
+    blocked_reason: PathBlockerReason
+    legacy_blocked_reason: str = ""
+    next_action: str = Field(min_length=1)
+    required_inputs: list[PathRequiredInput] = Field(default_factory=list)
+    human_decision_required: bool = False
+    human_decision_packet: JsonObject | None = None
+
+    @model_validator(mode="after")
+    def human_decision_requires_packet(self) -> PathResolutionBlocker:
+        if self.human_decision_required and self.human_decision_packet is None:
+            raise ValueError("human_decision_required requires human_decision_packet")
+        return self
+
+
+class PathResolutionResult(ContractModel):
+    status: Literal["ready", "blocked"]
+    paths: WorkbenchPathsConfig | None = None
+    blocker: PathResolutionBlocker | None = None
+
+    @model_validator(mode="after")
+    def status_matches_payload(self) -> PathResolutionResult:
+        if self.status == "ready" and self.blocker is not None:
+            raise ValueError("ready path resolution cannot include blocker")
+        if self.status == "ready" and self.paths is None:
+            raise ValueError("ready path resolution requires paths")
+        if self.status == "blocked" and self.blocker is None:
+            raise ValueError("blocked path resolution requires blocker")
+        return self
+
+
+class WikiPathResolutionPayload(ContractModel):
+    schema_: Literal["medical-notes-workbench.path-resolution.v1"] = Field(
+        "medical-notes-workbench.path-resolution.v1",
+        alias="schema",
+    )
+    phase: str = Field(min_length=1)
+    status: Literal["completed", "blocked"]
+    blocked_reason: str = ""
+    legacy_blocked_reason: str = ""
+    next_action: str = ""
+    required_inputs: list[str] = Field(default_factory=list)
+    wiki_dir: str = ""
+    wiki_source: str = ""
+    wiki_dir_source: str = ""
+    memory_path: str = ""
+    config_path: str = ""
+    candidates: list[JsonObject] = Field(default_factory=list)
+    compat_warnings: list[str] = Field(default_factory=list)
+    human_decision_required: bool = False
+    human_decision_packet: JsonObject | None = None
+    human_decision_packets: list[JsonObject] = Field(default_factory=list)
+
+
+def blocker_from_wiki_resolution(payload: dict[str, object]) -> PathResolutionBlocker:
+    resolution = WikiPathResolutionPayload.model_validate(payload)
+    raw_reason = resolution.blocked_reason
+    mapped_reason = _WIKI_REASON_MAP.get(raw_reason, _DEFAULT_REASON)
+    required_inputs: list[PathRequiredInput] = (
+        ["wiki_dir"]
+        if mapped_reason in {"paths.wiki_dir_missing", "paths.ambiguous", "paths.config_invalid"}
+        else []
+    )
+    return PathResolutionBlocker(
+        blocked_reason=mapped_reason,
+        legacy_blocked_reason=raw_reason,
+        next_action=resolution.next_action or "Configurar wiki_dir valido em /mednotes:setup.",
+        required_inputs=required_inputs,
+        human_decision_required=resolution.human_decision_required,
+        human_decision_packet=resolution.human_decision_packet,
+    )

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

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import re
+from typing import Literal
+
+from pydantic import Field, model_validator
+
+from mednotes.kernel.base import ContractModel
+
+WorkflowPublicObjectiveAnswer = Literal[
+    "yes",
+    "partial",
+    "no",
+    "waiting_agent",
+    "waiting_external",
+    "waiting_human",
+    "failed",
+]
+WorkflowPublicMutationState = Literal["changed", "unchanged", "not_applicable"]
+
+POSITIVE_FILE_COUNT_RE = re.compile(r"\b[1-9]\d*\s+arquivo")
+ZERO_FILE_COUNT_RE = re.compile(r"\b0\s+arquivo")
+
+
+class WorkflowPublicReportViewModel(ContractModel):
+    schema_: Literal["medical-notes-workbench.workflow-public-report-view-model.v1"] = Field(
+        "medical-notes-workbench.workflow-public-report-view-model.v1",
+        alias="schema",
+    )
+    workflow: str = Field(min_length=1)
+    run_id: str = Field(min_length=1)
+    objective_answer: WorkflowPublicObjectiveAnswer
+    headline: str = Field(min_length=1)
+    mutation_state: WorkflowPublicMutationState
+    mutation_summary: str = Field(min_length=1)
+    remaining_work_summary: str = Field(min_length=1)
+    next_step_summary: str = Field(min_length=1)
+    user_attention_required: bool
+    human_reason: str = ""
+    internal_terms_present: bool = False
+
+    @model_validator(mode="after")
+    def _public_report_is_coherent(self) -> WorkflowPublicReportViewModel:
+        folded_mutation = self.mutation_summary.casefold()
+        has_positive_file_count = POSITIVE_FILE_COUNT_RE.search(folded_mutation) is not None
+        has_only_zero_file_count = ZERO_FILE_COUNT_RE.search(folded_mutation) is not None and not has_positive_file_count
+        if self.mutation_state == "changed" and ("nada foi alterado" in folded_mutation or has_only_zero_file_count):
+            raise ValueError("public report mutation contradiction")
+        if self.user_attention_required and not self.human_reason.strip():
+            raise ValueError("public report user attention requires human reason")
+        if self.internal_terms_present:
+            raise ValueError("public report cannot expose internal terms")
+        return self