mednotes-opencode 0.1.0

package/.opencode/mednotes/src/mednotes/domains/wiki/flows/process_chats/process_chats_primary_objective.py

@@ -0,0 +1,28 @@
+"""Primary objective projection for `/mednotes:process-chats`.
+
+The FSM payload is the only source of truth. This module intentionally does not
+reconstruct success from old root fields such as `status`, `phase`,
+`blocked_reason`, `created_count` or `linker_applied`; those fields are legacy
+run-record evidence and must not fabricate a primary objective result.
+"""
+from __future__ import annotations
+
+from mednotes.domains.wiki.contracts.agent_report import ProcessChatsPrimaryObjectiveSummary
+from mednotes.domains.wiki.flows.process_chats.process_chats_fsm import PROCESS_CHATS_SCHEMA
+from mednotes.kernel.base import JsonObject, JsonObjectAdapter
+
+
+def process_chats_primary_objective_summary(payload: JsonObject) -> ProcessChatsPrimaryObjectiveSummary | None:
+    """Return the FSM-authored primary objective summary, if this is process-chats."""
+    normalized = JsonObjectAdapter.validate_python(payload)
+    schema = str(normalized["schema"]) if "schema" in normalized else ""
+    workflow = str(normalized["workflow"]) if "workflow" in normalized else ""
+    if schema != PROCESS_CHATS_SCHEMA or workflow != "/mednotes:process-chats":
+        return None
+
+    reports = JsonObjectAdapter.validate_python(normalized["reports"] if "reports" in normalized else {})
+    details = JsonObjectAdapter.validate_python(reports["details"] if "details" in reports else {})
+    if "primary_objective_summary" not in details:
+        return None
+    summary = JsonObjectAdapter.validate_python(details["primary_objective_summary"])
+    return ProcessChatsPrimaryObjectiveSummary.model_validate(summary)

package/.opencode/mednotes/src/mednotes/domains/wiki/flows/process_chats/process_chats_runtime_result.py

@@ -0,0 +1,185 @@
+"""Typed runtime boundary for `/mednotes:process-chats`.
+
+`publish-batch` still returns an operational JSON payload. This module owns the
+translation from that payload into one canonical `ProcessChatsMachine` event so
+the public projector in `process_chats_fsm.py` does not classify runtime status.
+"""
+
+from __future__ import annotations
+
+from mednotes.domains.wiki.flows.process_chats.process_chats_fsm import (
+    ProcessChatsFsmFacts,
+    ProcessChatsLinkerDiagnostic,
+    ProcessChatsOperationalSummary,
+    ProcessChatsPublishDiagnostic,
+    ProcessChatsPublishOperationResult,
+    build_process_chats_fsm_result,
+)
+from mednotes.domains.wiki.flows.process_chats.process_chats_machine import (
+    PROCESS_CHATS_WORKFLOW,
+    ProcessChatsErrorContext,
+    ProcessChatsPublishRuntimeObservation,
+    ProcessChatsPublishRuntimeObservedEvent,
+    ProcessChatsState,
+)
+from mednotes.kernel.base import JsonObject
+from mednotes.kernel.workflow import VersionControlSafety
+
+
+def process_chats_fsm_payload_from_publish_result(
+    result: JsonObject,
+    *,
+    run_id: str,
+    version_control_safety: VersionControlSafety | dict[str, object],
+) -> JsonObject:
+    return build_process_chats_fsm_result(
+        process_chats_fsm_facts_from_publish_result(
+            result,
+            run_id=run_id,
+            version_control_safety=version_control_safety,
+        )
+    ).to_payload()
+
+
+def process_chats_fsm_facts_from_publish_result(
+    result: JsonObject,
+    *,
+    run_id: str,
+    version_control_safety: VersionControlSafety | dict[str, object],
+) -> ProcessChatsFsmFacts:
+    typed_result = ProcessChatsPublishOperationResult.model_validate(result)
+    observation = _publish_observation_from_result(typed_result)
+    initial_state = _publish_observation_source_state(observation)
+    event = ProcessChatsPublishRuntimeObservedEvent(
+        workflow=PROCESS_CHATS_WORKFLOW,
+        run_id=run_id,
+        current_state=initial_state.value,
+        observation=observation,
+        audit_evidence=_publish_observation_audit_evidence(typed_result),
+    )
+    event_error_context = observation.error_context
+    error_context = typed_result.error_context
+    if not error_context and isinstance(event_error_context, ProcessChatsErrorContext):
+        error_context = event_error_context.to_payload()
+    return ProcessChatsFsmFacts(
+        run_id=run_id,
+        initial_state=initial_state,
+        event=event,
+        operational_summary=_operational_summary_from_publish_result(typed_result),
+        version_control_safety=version_control_safety,
+        error_context=error_context,
+    )
+
+
+def _publish_observation_from_result(result: ProcessChatsPublishOperationResult) -> ProcessChatsPublishRuntimeObservation:
+    """Return the canonical facts emitted by the publish/link producer."""
+
+    return result.runtime_observation
+
+
+def _publish_observation_source_state(observation: ProcessChatsPublishRuntimeObservation) -> ProcessChatsState:
+    """Use the validated entry state supplied with the canonical observation."""
+
+    return observation.source_state
+
+
+def _operational_summary_from_publish_result(
+    result: ProcessChatsPublishOperationResult,
+) -> ProcessChatsOperationalSummary:
+    """Build non-authoritative counts and diagnostics for reports only."""
+
+    linker = result.linker
+    return ProcessChatsOperationalSummary(
+        note_count=_note_count(result),
+        raw_count=_raw_count(result),
+        coverage_raw_count=_coverage_raw_count(result),
+        planned_note_count=_planned_note_count(result),
+        mutated=_mutated(result),
+        changed_files=_changed_files(result),
+        blocked_item_count=max(1, linker.blocker_count) if linker is not None and linker.blocker_count else 0,
+        next_action=result.next_action,
+        publish=ProcessChatsPublishDiagnostic(
+            status=result.status,
+            receipt_status=result.publish_receipt.status if result.publish_receipt is not None else "",
+            dry_run=result.dry_run,
+            manifest=result.manifest,
+            dry_run_receipt=result.dry_run_receipt,
+            new_taxonomy_leaf_authorization=result.new_taxonomy_leaf_authorization,
+        ),
+        linker=ProcessChatsLinkerDiagnostic(
+            status=linker.status if linker is not None else "",
+            next_action=linker.next_action if linker is not None else "",
+            diagnosis_status=linker.diagnosis_status if linker is not None else "",
+            applied=_linker_applied(result),
+            skipped_reason=result.linker_skipped_reason or (linker.linker_skipped_reason if linker is not None else ""),
+            blocker_count=linker.blocker_count if linker is not None else 0,
+        ),
+        artifacts=_artifacts(result),
+    )
+
+
+def _note_count(payload: ProcessChatsPublishOperationResult) -> int:
+    return payload.created_count or (payload.publish_receipt.published_count if payload.publish_receipt else 0) or len(payload.created)
+
+
+def _raw_count(payload: ProcessChatsPublishOperationResult) -> int:
+    return payload.processed_raw_count or len(payload.raw_updates)
+
+
+def _coverage_raw_count(payload: ProcessChatsPublishOperationResult) -> int:
+    coverage = payload.coverage_summary or payload.coverage
+    count = (coverage.raw_file_count if coverage is not None else 0) or (coverage.covered_count if coverage is not None else 0)
+    if count:
+        return count
+    total = 0
+    for batch in payload.planned_batches:
+        raw_files = batch.raw_files
+        total += len(raw_files)
+        if not raw_files and batch.raw_file:
+            total += 1
+    return total
+
+
+def _planned_note_count(payload: ProcessChatsPublishOperationResult) -> int:
+    return sum(len(batch.notes) for batch in payload.planned_batches)
+
+
+def _linker_applied(payload: ProcessChatsPublishOperationResult) -> bool:
+    return bool(payload.linker_applied or (payload.linker is not None and payload.linker.linker_applied))
+
+
+def _changed_files(payload: ProcessChatsPublishOperationResult) -> list[str]:
+    return [item for item in payload.created if item.strip()]
+
+
+def _mutated(payload: ProcessChatsPublishOperationResult) -> bool:
+    return not payload.dry_run and bool(_changed_files(payload) or _raw_count(payload))
+
+
+def _artifacts(publish_result: ProcessChatsPublishOperationResult) -> JsonObject:
+    artifacts: JsonObject = {}
+    if publish_result.manifest:
+        artifacts["manifest"] = publish_result.manifest
+    if publish_result.link_trigger_context_path:
+        artifacts["link_trigger_context_path"] = publish_result.link_trigger_context_path
+    if publish_result.linker_diagnosis_path:
+        artifacts["linker_diagnosis_path"] = publish_result.linker_diagnosis_path
+    if publish_result.linker_receipt_path:
+        artifacts["linker_receipt_path"] = publish_result.linker_receipt_path
+    if publish_result.dry_run_receipt is not None and publish_result.dry_run_receipt.path:
+        artifacts["dry_run_receipt_manifest"] = publish_result.dry_run_receipt.path
+    return artifacts
+
+
+def _publish_observation_audit_evidence(result: ProcessChatsPublishOperationResult) -> JsonObject:
+    return {
+        "adapter_schema": result.schema_id or "",
+        "adapter_phase": result.phase,
+        "adapter_status": result.status,
+        "adapter_reason": result.blocked_reason,
+        "counts": {
+            "created_count": result.created_count,
+            "processed_raw_count": result.processed_raw_count,
+            "changed_file_count": len(_changed_files(result)),
+        },
+    }

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

@@ -0,0 +1,97 @@
+"""Small cooperative pacing helpers for long interactive wiki workflows."""
+from __future__ import annotations
+
+import time
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+
+SleepFn = Callable[[float], None]
+
+
+@dataclass(frozen=True)
+class CooperativeCpuYieldSettings:
+    enabled: bool
+    every: int
+    seconds: float
+
+
+_CPU_YIELD_ENABLED: ContextVar[bool] = ContextVar("mednotes_cpu_yield_enabled", default=False)
+_CPU_YIELD_EVERY: ContextVar[int] = ContextVar("mednotes_cpu_yield_every", default=32)
+_CPU_YIELD_SECONDS: ContextVar[float] = ContextVar("mednotes_cpu_yield_seconds", default=0.0)
+_CPU_YIELD_SLEEP: ContextVar[SleepFn] = ContextVar("mednotes_cpu_yield_sleep", default=time.sleep)
+
+
+def _positive_int_from_env(name: str, default: int) -> int:
+    import os
+
+    raw = os.environ.get(name)
+    if raw is None:
+        return default
+    try:
+        value = int(raw)
+    except ValueError:
+        return default
+    return max(1, value)
+
+
+def _non_negative_float_from_env(name: str, default: float) -> float:
+    import os
+
+    raw = os.environ.get(name)
+    if raw is None:
+        return default
+    try:
+        value = float(raw)
+    except ValueError:
+        return default
+    return max(0.0, value)
+
+
+def cooperative_cpu_yield_settings_from_env(
+    *,
+    default_enabled: bool,
+    default_every: int = 2,
+    default_seconds: float = 0.0025,
+) -> CooperativeCpuYieldSettings:
+    import os
+
+    enabled = default_enabled and os.environ.get("MEDNOTES_CPU_YIELD_DISABLED") != "1"
+    return CooperativeCpuYieldSettings(
+        enabled=enabled,
+        every=_positive_int_from_env("MEDNOTES_CPU_YIELD_EVERY", default_every),
+        seconds=_non_negative_float_from_env("MEDNOTES_CPU_YIELD_SECONDS", default_seconds),
+    )
+
+
+@contextmanager
+def cooperative_cpu_yield_scope(
+    *,
+    enabled: bool,
+    every: int = 32,
+    seconds: float = 0.005,
+    sleep: SleepFn = time.sleep,
+) -> Iterator[None]:
+    enabled_token = _CPU_YIELD_ENABLED.set(enabled)
+    every_token = _CPU_YIELD_EVERY.set(max(1, int(every or 1)))
+    seconds_token = _CPU_YIELD_SECONDS.set(max(0.0, float(seconds or 0.0)))
+    sleep_token = _CPU_YIELD_SLEEP.set(sleep)
+    try:
+        yield
+    finally:
+        _CPU_YIELD_SLEEP.reset(sleep_token)
+        _CPU_YIELD_SECONDS.reset(seconds_token)
+        _CPU_YIELD_EVERY.reset(every_token)
+        _CPU_YIELD_ENABLED.reset(enabled_token)
+
+
+def cooperative_cpu_yield(index: int) -> None:
+    if not _CPU_YIELD_ENABLED.get():
+        return
+    seconds = _CPU_YIELD_SECONDS.get()
+    if seconds <= 0:
+        return
+    every = _CPU_YIELD_EVERY.get()
+    if index > 0 and index % every == 0:
+        _CPU_YIELD_SLEEP.get()(seconds)

package/.opencode/mednotes/src/mednotes/kernel/__init__.py

@@ -0,0 +1,6 @@
+"""Shared kernel — generic workflow/FSM building blocks (DDD shared kernel).
+
+Domain-free: no bounded-context concept lives here. The kernel is the low layer;
+domains import the kernel, never the reverse.
+Enforced by tools/audit/import_layering.py.
+"""

package/.opencode/mednotes/src/mednotes/kernel/agent_directive.py

@@ -0,0 +1,336 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Literal
+
+from pydantic import Field, ValidationInfo, field_validator, model_validator
+
+from mednotes.kernel.base import ContractModel, JsonObject, JsonObjectAdapter
+from mednotes.kernel.effects import WorkflowEffect, WorkflowEffectKind
+from mednotes.kernel.progress import WorkflowProgressStatus, WorkflowProgressViewModel
+from mednotes.kernel.state_machine import WorkflowStateMachineSnapshot
+
+AgentDirectiveStatus = Literal[
+    "running",
+    "waiting_agent",
+    "waiting_external",
+    "waiting_human",
+    "blocked",
+    "failed",
+    "completed",
+    "completed_with_warnings",
+]
+
+AGENT_DIRECTIVE_SCHEMA = "agent-directive.v1"
+
+
+class AgentCapabilities(ContractModel):
+    continue_: bool = Field(False, alias="continue")
+    final_report: bool = False
+
+
+class AgentLimits(ContractModel):
+    raw_content: bool = False
+    absolute_paths: bool = False
+    ad_hoc_scripts: bool = False
+
+
+class AgentEffect(ContractModel):
+    """Redacted executable effect projection for hooks and agent automation.
+
+    The directive is the public FSM -> agent contract. It exposes enough typed
+    effect identity to continue safely, without making hooks reconstruct work
+    from diagnostic evidence or opaque adapter payload fields.
+    """
+
+    effect_id: str = ""
+    kind: WorkflowEffectKind
+    target: str = ""
+    origin_state: str = ""
+    resume_action: str = ""
+    mutates_resources: bool = False
+    no_resource_mutation: bool = False
+    rollback_declared: bool = False
+    requires_receipt: bool = True
+    requires_attestation: bool = False
+    model_policy: JsonObject = Field(default_factory=dict)
+    metadata: JsonObject = Field(default_factory=dict)
+    payload_schema: str = ""
+    payload: JsonObject = Field(default_factory=dict)
+
+
+class AgentReportDirective(ContractModel):
+    requires: list[str] = Field(default_factory=list)
+
+
+class AgentDirectiveControl(ContractModel):
+    status: AgentDirectiveStatus
+    state: str = Field(min_length=1, pattern=r"\S")
+    reason: str = ""
+    phase: str = ""
+    capabilities: AgentCapabilities = Field(default_factory=AgentCapabilities)
+    effects: list[AgentEffect] = Field(default_factory=list)
+    blockers: list[str] = Field(default_factory=list)
+    resume: str = ""
+    report: AgentReportDirective = Field(default_factory=AgentReportDirective)
+    limits: AgentLimits = Field(default_factory=AgentLimits)
+
+    @field_validator("state")
+    @classmethod
+    def _state_must_be_identity_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
+
+    @field_validator("blockers")
+    @classmethod
+    def _blockers_must_be_text(cls, value: list[str]) -> list[str]:
+        return [item.strip() for item in value if item.strip()]
+
+    @model_validator(mode="after")
+    def _status_shape(self) -> AgentDirectiveControl:
+        if self.status == "waiting_agent":
+            if not self.capabilities.continue_:
+                raise ValueError("waiting_agent requires control.capabilities.continue=true")
+            if self.capabilities.final_report:
+                raise ValueError("waiting_agent requires control.capabilities.final_report=false")
+            if not self.effects:
+                raise ValueError("waiting_agent requires agent_directive.control.effects")
+        if self.status in {"completed", "completed_with_warnings"}:
+            if not self.capabilities.final_report:
+                raise ValueError("completed directive requires control.capabilities.final_report=true")
+        if self.status in {"waiting_human", "waiting_external", "blocked", "failed"}:
+            if not self.blockers and not self.resume.strip():
+                raise ValueError(f"{self.status} directive requires blockers or resume")
+        return self
+
+
+class AgentDirective(ContractModel):
+    # The kernel is framework-only, so its default schema is neutral. Product
+    # workflows must pass their public schema explicitly at the projection edge.
+    schema_: str = Field(AGENT_DIRECTIVE_SCHEMA, alias="schema")
+    workflow: str = Field(min_length=1, pattern=r"\S")
+    run_id: str = Field(min_length=1, pattern=r"\S")
+    control: AgentDirectiveControl
+    summary: str = ""
+    instructions: list[str] = Field(default_factory=list)
+
+    @field_validator("workflow", "run_id")
+    @classmethod
+    def _identity_fields_must_be_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
+
+    @field_validator("instructions")
+    @classmethod
+    def _instructions_are_plain_text(cls, value: list[str]) -> list[str]:
+        cleaned: list[str] = []
+        for line in value:
+            text = line.strip()
+            if not text:
+                continue
+            if text.casefold().startswith("agent_instruction:"):
+                raise ValueError("AgentDirective instructions must not include agent_instruction prefix")
+            cleaned.append(text)
+        return cleaned
+
+
+def _json_str_field(payload: JsonObject, key: str) -> str:
+    value = payload[key] if key in payload else ""
+    return value if isinstance(value, str) else ""
+
+
+def assert_agent_directive_matches_progress(
+    directive: AgentDirective,
+    *,
+    workflow: str,
+    run_id: str,
+    progress_view_model: WorkflowProgressViewModel,
+    snapshot: WorkflowStateMachineSnapshot,
+    allowed_effect_kinds: set[WorkflowEffectKind],
+    label: str,
+) -> None:
+    """Assert the agent-facing route is a projection of the current FSM state.
+
+    The directive is executable by hooks/subagents, so it cannot be validated as
+    a standalone object. It must agree with the current StateChart leaf, progress
+    model and effect policy; otherwise it becomes a parallel state channel.
+    """
+
+    if directive.workflow != workflow:
+        raise ValueError(f"{label} agent_directive workflow must match workflow")
+    if directive.run_id != run_id or directive.run_id != snapshot.run_id or directive.run_id != progress_view_model.run_id:
+        raise ValueError(f"{label} agent_directive run_id must match progress and snapshot")
+    if progress_view_model.workflow != workflow or snapshot.workflow != workflow:
+        raise ValueError(f"{label} progress and snapshot workflow must match workflow")
+    if directive.control.status != progress_view_model.status.value:
+        raise ValueError(f"{label} agent_directive status must match progress view status")
+    if progress_view_model.status.value != snapshot.current_category.value:
+        raise ValueError(f"{label} progress status must match state_machine_snapshot category")
+    if directive.control.state != snapshot.current_state:
+        raise ValueError(f"{label} agent_directive state must match current StateChart state")
+    if progress_view_model.state != snapshot.current_state:
+        raise ValueError(f"{label} progress state must match current StateChart state")
+    if directive.control.capabilities.continue_ != progress_view_model.can_continue_now:
+        raise ValueError(f"{label} agent_directive continue capability must match progress view")
+    final_report = progress_view_model.status in {
+        WorkflowProgressStatus.COMPLETED,
+        WorkflowProgressStatus.COMPLETED_WITH_WARNINGS,
+    }
+    if directive.control.capabilities.final_report != final_report:
+        raise ValueError(f"{label} agent_directive final_report capability must match progress status")
+    for effect in directive.control.effects:
+        if effect.origin_state != snapshot.current_state:
+            raise ValueError(f"{label} agent_directive effect origin_state must match current state")
+        if effect.kind not in allowed_effect_kinds:
+            raise ValueError(f"{label} agent_directive effect kind is not allowed for current state")
+
+
+def agent_directive_from_progress_view_model(
+    view_model: WorkflowProgressViewModel,
+    *,
+    schema: str = AGENT_DIRECTIVE_SCHEMA,
+    reason: str,
+    report_requires: list[str],
+    summary: str,
+    effects: Sequence[WorkflowEffect | AgentEffect | JsonObject] | None = None,
+    blockers: list[str] | None = None,
+    resume: str = "",
+    instructions: list[str] | None = None,
+    effect_payload_projector: Callable[[object], JsonObject] | None = None,
+) -> AgentDirective:
+    status = _directive_status(view_model.status)
+    final_report = status in {"completed", "completed_with_warnings"}
+    required_reason = _required_directive_text(reason, field_name="reason")
+    required_summary = _required_directive_text(summary, field_name="summary")
+    required_report_requires = _required_directive_report_requires(report_requires)
+    control = {
+        "status": status,
+        "state": view_model.state,
+        "phase": view_model.phase,
+        "reason": required_reason,
+        "capabilities": {
+            "continue": view_model.can_continue_now,
+            "final_report": final_report,
+        },
+        "effects": [
+            _project_agent_effect(
+                effect,
+                effect_payload_projector=effect_payload_projector or _default_effect_payload_projector,
+            ).to_payload()
+            for effect in effects or []
+        ],
+        "blockers": blockers or [],
+        "resume": resume or view_model.resume_action or "",
+        "report": {"requires": required_report_requires},
+        "limits": {
+            "raw_content": False,
+            "absolute_paths": False,
+            "ad_hoc_scripts": False,
+        },
+    }
+    return AgentDirective.model_validate(
+        {
+            "schema": schema,
+            "workflow": view_model.workflow,
+            "run_id": view_model.run_id,
+            "control": control,
+            "summary": required_summary,
+            "instructions": instructions or _directive_instructions(status),
+        }
+    )
+
+
+def _project_agent_effect(
+    effect: WorkflowEffect | AgentEffect | JsonObject,
+    *,
+    effect_payload_projector: Callable[[object], JsonObject],
+) -> AgentEffect:
+    if isinstance(effect, AgentEffect):
+        return effect
+    if isinstance(effect, WorkflowEffect):
+        payload = effect_payload_projector(effect.payload)
+        return AgentEffect.model_validate(
+            {
+                "effect_id": effect.effect_id,
+                "kind": effect.kind,
+                "target": effect.target,
+                "origin_state": effect.origin_state,
+                "resume_action": effect.resume_action,
+                "mutates_resources": effect.mutates_resources,
+                "no_resource_mutation": effect.no_resource_mutation,
+                "rollback_declared": effect.rollback_declared,
+                "requires_receipt": effect.requires_receipt,
+                "requires_attestation": effect.requires_attestation,
+                "model_policy": effect.model_policy,
+                "metadata": effect.metadata,
+                "payload_schema": _json_str_field(payload, "schema"),
+                "payload": payload,
+            }
+        )
+    return AgentEffect.model_validate(effect)
+
+
+def _default_effect_payload_projector(value: object) -> JsonObject:
+    """Validate effect payloads without applying domain-specific redaction."""
+
+    return JsonObjectAdapter.validate_python(value)
+
+
+def _directive_status(status: WorkflowProgressStatus) -> str:
+    match status:
+        case WorkflowProgressStatus.RUNNING:
+            return "running"
+        case WorkflowProgressStatus.WAITING_AGENT:
+            return "waiting_agent"
+        case WorkflowProgressStatus.WAITING_EXTERNAL:
+            return "waiting_external"
+        case WorkflowProgressStatus.WAITING_HUMAN:
+            return "waiting_human"
+        case WorkflowProgressStatus.BLOCKED:
+            return "blocked"
+        case WorkflowProgressStatus.FAILED:
+            return "failed"
+        case WorkflowProgressStatus.COMPLETED:
+            return "completed"
+        case WorkflowProgressStatus.COMPLETED_WITH_WARNINGS:
+            return "completed_with_warnings"
+        case WorkflowProgressStatus.IDLE:
+            raise ValueError("idle progress cannot produce agent directive")
+
+
+def _directive_instructions(status: str) -> list[str]:
+    match status:
+        case "running":
+            return ["aguarde o resultado final do workflow antes de concluir."]
+        case "waiting_agent":
+            return ["continue pela rota oficial antes do relatorio final."]
+        case "waiting_external":
+            return ["reporte o progresso parcial e aguarde a condicao externa."]
+        case "waiting_human":
+            return ["peca a decisao humana pelo pacote oficial antes de continuar."]
+        case "blocked":
+            return ["reporte o bloqueio literal; nao declare sucesso do workflow."]
+        case "failed":
+            return ["reporte a falha literal e o contexto de erro."]
+        case "completed" | "completed_with_warnings":
+            return ["escreva o relatorio final usando os relatorios oficiais."]
+        case _:
+            raise ValueError(f"unsupported directive status: {status}")
+
+
+def _required_directive_text(value: str, *, field_name: str) -> str:
+    cleaned = value.strip()
+    if not cleaned:
+        raise ValueError(f"{field_name} must be non-empty")
+    return cleaned
+
+
+def _required_directive_report_requires(value: list[str]) -> list[str]:
+    cleaned = [item.strip() for item in value if item.strip()]
+    if not cleaned:
+        raise ValueError("report_requires must be non-empty")
+    return cleaned