mednotes-opencode 0.1.0

package/.opencode/mednotes/src/mednotes/domains/wiki/flows/fix_wiki/fix_wiki_states.py

@@ -0,0 +1,290 @@
+"""Canonical fix-wiki StateChart states and state-category mapping.
+
+This module is pure domain data shared by the machine and public projector.
+`fix_wiki_machine.py` owns transitions; `fix_wiki_fsm.py` only projects the
+machine result and must not be imported by the machine for state truth.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from mednotes.kernel.state_machine import WorkflowStateCategory
+
+FIX_WIKI_WORKFLOW = "/mednotes:fix-wiki"
+
+
+class FixWikiState(StrEnum):
+    """Canonical leaf states for the fix-wiki StateChart."""
+
+    DIAGNOSIS_RUNNING = "diagnosis.running"
+    ENVIRONMENT_PATHS_MISSING = "environment.paths_missing"
+    ENVIRONMENT_WIKI_DIR_MISSING = "environment.wiki_dir_missing"
+    ENVIRONMENT_WINDOWS_PATH_OR_VENV_BLOCKED = "environment.windows_path_or_venv_blocked"
+    VAULT_GUARD_RUNNING = "vault_guard.running"
+    VAULT_GUARD_DECISION_REQUIRED = "vault_guard.decision_required"
+    SUBAGENT_PLAN_ATTESTATION_REQUIRED = "subagent_plan_attestation.required"
+    SUBAGENT_PLAN_ATTESTATION_INVALID = "subagent_plan_attestation.invalid"
+    AGENT_TOOL_CONTRACT_VIOLATION = "agent_tool_contract_violation"
+    DETERMINISTIC_REPAIRS_RUNNING = "deterministic_repairs.running"
+    DETERMINISTIC_REPAIRS_FAILED = "deterministic_repairs.failed"
+    STYLE_REWRITE_SPECIALIST_REQUESTED = "style_rewrite.specialist_requested"
+    STYLE_REWRITE_CAPACITY_WAIT = "style_rewrite.capacity_wait"
+    STYLE_REWRITE_REVIEW_REQUIRED = "style_rewrite.review_required"
+    STYLE_REWRITE_APPLY_RUNNING = "style_rewrite.apply_running"
+    TAXONOMY_DECISION_REQUIRED = "taxonomy.decision_required"
+    TAXONOMY_APPLY_RUNNING = "taxonomy.apply_running"
+    VOCABULARY_CURATOR_RUNNING = "vocabulary.curator_running"
+    VOCABULARY_SEMANTIC_INGESTION_PENDING = "vocabulary.semantic_ingestion_pending"
+    VOCABULARY_EVAL_RUNNING = "vocabulary.eval_running"
+    VOCABULARY_EVAL_NEEDS_REVIEW = "vocabulary.eval_needs_review"
+    VOCABULARY_APPLY_RUNNING = "vocabulary.apply_running"
+    VOCABULARY_SQLITE_INTEGRITY_FAILED = "vocabulary.sqlite_integrity_failed"
+    ATOMICITY_SPLIT_RUNNING = "atomicity_split.running"
+    ATOMICITY_SPLIT_REVIEW_REQUIRED = "atomicity_split.review_required"
+    RELATED_NOTES_EXPORT_RUNNING = "related_notes.export_running"
+    RELATED_NOTES_QUOTA_WAIT = "related_notes.quota_wait"
+    RELATED_NOTES_OBSIDIAN_NOT_READY = "related_notes.obsidian_not_ready"
+    RELATED_NOTES_BLOCKED = "related_notes.blocked"
+    LINK_RUN_REQUESTED = "link.run_requested"
+    LINK_GRAPH_BLOCKED = "link.graph_blocked"
+    LINK_GRAPH_REVIEW_REQUIRED = "link.graph_review_required"
+    LINKER_BLOCKED = "link.linker_blocked"
+    MERGE_RUNNING = "merge.running"
+    MERGE_REVIEW_REQUIRED = "merge.review_required"
+    CONTRACT_GAP_MISSING_NEXT_ACTION = "contract_gap.missing_next_action"
+    CONTRACT_GAP_MISSING_ERROR_CONTEXT = "contract_gap.missing_error_context"
+    ROLLBACK_RUNNING = "rollback.running"
+    ROLLBACK_PERFORMED = "rollback.performed"
+    ROLLBACK_FAILED = "rollback.failed"
+    FINAL_VALIDATION_RUNNING = "final_validation.running"
+    FINAL_VALIDATION_FAILED = "final_validation.failed"
+    PREVIEW_READY = "preview.ready"
+    COMPLETED = "completed"
+    COMPLETED_WITH_WARNINGS = "completed_with_warnings"
+    FAILED = "failed"
+
+
+class FixWikiDiagnosisLane(StrEnum):
+    """Typed diagnosis lanes; guards are allowed to inspect only this value."""
+
+    ENVIRONMENT_PATHS_MISSING = "environment.paths_missing"
+    ENVIRONMENT_WIKI_DIR_MISSING = "environment.wiki_dir_missing"
+    ENVIRONMENT_WINDOWS_PATH_OR_VENV_BLOCKED = "environment.windows_path_or_venv_blocked"
+    VAULT_GUARD_DECISION_REQUIRED = "vault_guard.decision_required"
+    SUBAGENT_PLAN_ATTESTATION_REQUIRED = "subagent_plan_attestation.required"
+    SUBAGENT_PLAN_ATTESTATION_INVALID = "subagent_plan_attestation.invalid"
+    AGENT_TOOL_CONTRACT_VIOLATION = "agent_tool_contract_violation"
+    DETERMINISTIC_REPAIRS = "deterministic_repairs"
+    STYLE_REWRITE = "style_rewrite"
+    TAXONOMY = "taxonomy"
+    VOCABULARY_SEMANTIC_INGESTION_PENDING = "vocabulary.semantic_ingestion_pending"
+    VOCABULARY = "vocabulary"
+    ATOMICITY_SPLIT = "atomicity_split"
+    MERGE = "merge"
+    RELATED_NOTES = "related_notes"
+    LINK = "link"
+    CONTRACT_GAP_MISSING_NEXT_ACTION = "contract_gap.missing_next_action"
+    CONTRACT_GAP_MISSING_ERROR_CONTEXT = "contract_gap.missing_error_context"
+    ROLLBACK = "rollback"
+    FINAL_VALIDATION = "final_validation"
+
+
+class FixWikiReason(StrEnum):
+    """Closed public reason labels derived from fix-wiki leaf states."""
+
+    COMPLETED = "completed"
+    COMPLETED_WITH_WARNINGS = "completed_with_warnings"
+    PREVIEW_READY = "preview_ready"
+    ENVIRONMENT_PATHS_MISSING = "environment.paths_missing"
+    ENVIRONMENT_WIKI_DIR_MISSING = "environment.wiki_dir_missing"
+    ENVIRONMENT_WINDOWS_PATH_OR_VENV_BLOCKED = "environment.windows_path_or_venv_blocked"
+    WAITING_EXTERNAL_RELATED_NOTES = "waiting_external_related_notes"
+    WAITING_EXTERNAL = "waiting_external"
+    WAITING_HUMAN = "waiting_human"
+    SUBAGENT_PLAN_ATTESTATION_REQUIRED = "subagent_plan_attestation_required"
+    SUBAGENT_PLAN_ATTESTATION_INVALID = "subagent_plan_attestation_invalid"
+    STYLE_REWRITE_REVIEW_REQUIRED = "style_rewrite_review_required"
+    TAXONOMY_DECISION_REQUIRED = "taxonomy_decision_required"
+    VOCABULARY_EVAL_NEEDS_REVIEW = "vocabulary_eval_needs_review"
+    ATOMICITY_SPLIT_REVIEW_REQUIRED = "atomicity_split_review_required"
+    MERGE_REVIEW_REQUIRED = "merge_review_required"
+    STYLE_REWRITE_READY = "style_rewrite_ready"
+    VOCABULARY_SEMANTIC_INGESTION_PENDING = "vocabulary_semantic_ingestion_pending"
+    GRAPH_BLOCKED = "graph_blocked"
+    ATOMICITY_SPLIT_REQUIRED = "atomicity_split_required"
+    RELATED_NOTES_BLOCKED = "related_notes_blocked"
+    LINK_RUN_REQUESTED = "link_run_requested"
+    LINKER_BLOCKED = "linker_blocked"
+    GRAPH_REVIEW_REQUIRED = "graph_review_required"
+    TAXONOMY_BLOCKED = "taxonomy_blocked"
+    VAULT_GUARD_REQUIRED = "vault_guard_required"
+    STYLE_REWRITE_REQUIRED = "style_rewrite_required"
+    FAILED = "failed"
+
+
+FIX_WIKI_DIAGNOSIS_PRIORITY: tuple[FixWikiDiagnosisLane, ...] = (
+    FixWikiDiagnosisLane.ENVIRONMENT_PATHS_MISSING,
+    FixWikiDiagnosisLane.ENVIRONMENT_WIKI_DIR_MISSING,
+    FixWikiDiagnosisLane.ENVIRONMENT_WINDOWS_PATH_OR_VENV_BLOCKED,
+    FixWikiDiagnosisLane.VAULT_GUARD_DECISION_REQUIRED,
+    FixWikiDiagnosisLane.SUBAGENT_PLAN_ATTESTATION_REQUIRED,
+    FixWikiDiagnosisLane.SUBAGENT_PLAN_ATTESTATION_INVALID,
+    FixWikiDiagnosisLane.AGENT_TOOL_CONTRACT_VIOLATION,
+    FixWikiDiagnosisLane.DETERMINISTIC_REPAIRS,
+    FixWikiDiagnosisLane.STYLE_REWRITE,
+    FixWikiDiagnosisLane.TAXONOMY,
+    FixWikiDiagnosisLane.VOCABULARY_SEMANTIC_INGESTION_PENDING,
+    FixWikiDiagnosisLane.VOCABULARY,
+    FixWikiDiagnosisLane.ATOMICITY_SPLIT,
+    FixWikiDiagnosisLane.MERGE,
+    FixWikiDiagnosisLane.RELATED_NOTES,
+    FixWikiDiagnosisLane.LINK,
+    FixWikiDiagnosisLane.CONTRACT_GAP_MISSING_NEXT_ACTION,
+    FixWikiDiagnosisLane.CONTRACT_GAP_MISSING_ERROR_CONTEXT,
+    FixWikiDiagnosisLane.ROLLBACK,
+    FixWikiDiagnosisLane.FINAL_VALIDATION,
+)
+
+
+def category_for_state(state: str | FixWikiState) -> WorkflowStateCategory:
+    """Map every fix-wiki leaf state to the public FSM category."""
+
+    try:
+        state_value = state if isinstance(state, FixWikiState) else FixWikiState(str(state))
+    except ValueError as exc:
+        raise ValueError(f"unknown fix-wiki state: {state}") from exc
+
+    match state_value:
+        case (
+            FixWikiState.DIAGNOSIS_RUNNING
+            | FixWikiState.VAULT_GUARD_RUNNING
+            | FixWikiState.DETERMINISTIC_REPAIRS_RUNNING
+            | FixWikiState.STYLE_REWRITE_APPLY_RUNNING
+            | FixWikiState.TAXONOMY_APPLY_RUNNING
+            | FixWikiState.VOCABULARY_CURATOR_RUNNING
+            | FixWikiState.VOCABULARY_EVAL_RUNNING
+            | FixWikiState.VOCABULARY_APPLY_RUNNING
+            | FixWikiState.ATOMICITY_SPLIT_RUNNING
+            | FixWikiState.RELATED_NOTES_EXPORT_RUNNING
+            | FixWikiState.LINK_RUN_REQUESTED
+            | FixWikiState.MERGE_RUNNING
+            | FixWikiState.ROLLBACK_RUNNING
+            | FixWikiState.FINAL_VALIDATION_RUNNING
+        ):
+            return WorkflowStateCategory.RUNNING
+        case (
+            FixWikiState.STYLE_REWRITE_SPECIALIST_REQUESTED
+            | FixWikiState.VOCABULARY_SEMANTIC_INGESTION_PENDING
+        ):
+            return WorkflowStateCategory.WAITING_AGENT
+        case (
+            FixWikiState.STYLE_REWRITE_CAPACITY_WAIT
+            | FixWikiState.RELATED_NOTES_QUOTA_WAIT
+        ):
+            return WorkflowStateCategory.WAITING_EXTERNAL
+        case (
+            FixWikiState.STYLE_REWRITE_REVIEW_REQUIRED
+            | FixWikiState.TAXONOMY_DECISION_REQUIRED
+            | FixWikiState.SUBAGENT_PLAN_ATTESTATION_REQUIRED
+            | FixWikiState.SUBAGENT_PLAN_ATTESTATION_INVALID
+            | FixWikiState.VOCABULARY_EVAL_NEEDS_REVIEW
+            | FixWikiState.ATOMICITY_SPLIT_REVIEW_REQUIRED
+            | FixWikiState.MERGE_REVIEW_REQUIRED
+            | FixWikiState.LINK_GRAPH_REVIEW_REQUIRED
+        ):
+            return WorkflowStateCategory.WAITING_HUMAN
+        case (
+            FixWikiState.ENVIRONMENT_PATHS_MISSING
+            | FixWikiState.ENVIRONMENT_WIKI_DIR_MISSING
+            | FixWikiState.ENVIRONMENT_WINDOWS_PATH_OR_VENV_BLOCKED
+            | FixWikiState.RELATED_NOTES_OBSIDIAN_NOT_READY
+            | FixWikiState.RELATED_NOTES_BLOCKED
+            | FixWikiState.LINK_GRAPH_BLOCKED
+            | FixWikiState.LINKER_BLOCKED
+            | FixWikiState.VAULT_GUARD_DECISION_REQUIRED
+            | FixWikiState.ROLLBACK_FAILED
+        ):
+            return WorkflowStateCategory.BLOCKED
+        case (
+            FixWikiState.FAILED
+            | FixWikiState.AGENT_TOOL_CONTRACT_VIOLATION
+            | FixWikiState.CONTRACT_GAP_MISSING_NEXT_ACTION
+            | FixWikiState.CONTRACT_GAP_MISSING_ERROR_CONTEXT
+            | FixWikiState.DETERMINISTIC_REPAIRS_FAILED
+            | FixWikiState.VOCABULARY_SQLITE_INTEGRITY_FAILED
+            | FixWikiState.ROLLBACK_PERFORMED
+            | FixWikiState.FINAL_VALIDATION_FAILED
+        ):
+            return WorkflowStateCategory.FAILED
+        case FixWikiState.COMPLETED:
+            return WorkflowStateCategory.COMPLETED
+        case FixWikiState.PREVIEW_READY:
+            return WorkflowStateCategory.COMPLETED
+        case FixWikiState.COMPLETED_WITH_WARNINGS:
+            return WorkflowStateCategory.COMPLETED_WITH_WARNINGS
+        case _:
+            raise AssertionError(f"unclassified fix-wiki state: {state_value}")
+
+
+def reason_for_state(state: str | FixWikiState) -> FixWikiReason:
+    """Derive the public reason from the canonical leaf state only.
+
+    Runtime outcomes and transition metadata may be useful audit evidence, but
+    they are not allowed to override this map. If a reason needs to become more
+    specific, the fix is to add a precise leaf state rather than a second
+    status/reason channel.
+    """
+
+    state_value = state if isinstance(state, FixWikiState) else FixWikiState(str(state))
+    if state_value == FixWikiState.PREVIEW_READY:
+        return FixWikiReason.PREVIEW_READY
+    if state_value == FixWikiState.ENVIRONMENT_PATHS_MISSING:
+        return FixWikiReason.ENVIRONMENT_PATHS_MISSING
+    if state_value == FixWikiState.ENVIRONMENT_WIKI_DIR_MISSING:
+        return FixWikiReason.ENVIRONMENT_WIKI_DIR_MISSING
+    if state_value == FixWikiState.ENVIRONMENT_WINDOWS_PATH_OR_VENV_BLOCKED:
+        return FixWikiReason.ENVIRONMENT_WINDOWS_PATH_OR_VENV_BLOCKED
+    if state_value == FixWikiState.COMPLETED:
+        return FixWikiReason.COMPLETED
+    if state_value == FixWikiState.COMPLETED_WITH_WARNINGS:
+        return FixWikiReason.COMPLETED_WITH_WARNINGS
+    if state_value == FixWikiState.RELATED_NOTES_QUOTA_WAIT:
+        return FixWikiReason.WAITING_EXTERNAL_RELATED_NOTES
+    if state_value == FixWikiState.STYLE_REWRITE_CAPACITY_WAIT:
+        return FixWikiReason.WAITING_EXTERNAL
+    if state_value == FixWikiState.STYLE_REWRITE_SPECIALIST_REQUESTED:
+        return FixWikiReason.STYLE_REWRITE_READY
+    if state_value == FixWikiState.VOCABULARY_SEMANTIC_INGESTION_PENDING:
+        return FixWikiReason.VOCABULARY_SEMANTIC_INGESTION_PENDING
+    if state_value == FixWikiState.LINK_GRAPH_BLOCKED:
+        return FixWikiReason.GRAPH_BLOCKED
+    if state_value == FixWikiState.LINK_GRAPH_REVIEW_REQUIRED:
+        return FixWikiReason.GRAPH_REVIEW_REQUIRED
+    if state_value == FixWikiState.LINK_RUN_REQUESTED:
+        return FixWikiReason.LINK_RUN_REQUESTED
+    if state_value == FixWikiState.LINKER_BLOCKED:
+        return FixWikiReason.LINKER_BLOCKED
+    if state_value in {FixWikiState.RELATED_NOTES_BLOCKED, FixWikiState.RELATED_NOTES_OBSIDIAN_NOT_READY}:
+        return FixWikiReason.RELATED_NOTES_BLOCKED
+    if state_value == FixWikiState.ATOMICITY_SPLIT_REVIEW_REQUIRED:
+        return FixWikiReason.ATOMICITY_SPLIT_REVIEW_REQUIRED
+    if state_value == FixWikiState.TAXONOMY_DECISION_REQUIRED:
+        return FixWikiReason.TAXONOMY_DECISION_REQUIRED
+    if state_value == FixWikiState.VAULT_GUARD_DECISION_REQUIRED:
+        return FixWikiReason.VAULT_GUARD_REQUIRED
+    if state_value == FixWikiState.STYLE_REWRITE_REVIEW_REQUIRED:
+        return FixWikiReason.STYLE_REWRITE_REVIEW_REQUIRED
+    if state_value == FixWikiState.SUBAGENT_PLAN_ATTESTATION_REQUIRED:
+        return FixWikiReason.SUBAGENT_PLAN_ATTESTATION_REQUIRED
+    if state_value == FixWikiState.SUBAGENT_PLAN_ATTESTATION_INVALID:
+        return FixWikiReason.SUBAGENT_PLAN_ATTESTATION_INVALID
+    if state_value == FixWikiState.VOCABULARY_EVAL_NEEDS_REVIEW:
+        return FixWikiReason.VOCABULARY_EVAL_NEEDS_REVIEW
+    if state_value == FixWikiState.MERGE_REVIEW_REQUIRED:
+        return FixWikiReason.MERGE_REVIEW_REQUIRED
+    if category_for_state(state_value) == WorkflowStateCategory.WAITING_HUMAN:
+        return FixWikiReason.WAITING_HUMAN
+    if category_for_state(state_value) == WorkflowStateCategory.FAILED:
+        return FixWikiReason.FAILED
+    return FixWikiReason.FAILED

package/.opencode/mednotes/src/mednotes/domains/wiki/flows/fix_wiki/fix_wiki_user_report.py

@@ -0,0 +1,342 @@
+"""Human-readable redacted report for the `fix-wiki` workflow."""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field, StrictBool, StrictStr
+
+from mednotes.domains.wiki.capabilities.notes.raw_chats import atomic_write_text
+from mednotes.domains.wiki.flows.fix_wiki.fix_wiki_fsm import assert_fix_wiki_fsm_payload
+from mednotes.domains.wiki.flows.fix_wiki.fix_wiki_primary_objective import fix_wiki_primary_objective_summary
+from mednotes.kernel.base import JsonArrayAdapter, JsonObject, JsonObjectAdapter, JsonValue
+from mednotes.kernel.public_report import WorkflowPublicReport
+
+_SEVERITY_ORDER = {"critical": 0, "high": 1, "medium": 2, "low": 3, "info": 4, "": 5}
+_TRANSIENT_MUTATION_LINE_RE = re.compile(r"\balterei\s+\d+\s+arquivo", re.IGNORECASE)
+_PUBLIC_GRAPH_CURATION_ACTION = "Retomar a curadoria do grafo pela rota oficial antes de concluir a atualização de links."
+_PUBLIC_HUMAN_DECISION_RESUME = "Após escolher uma opção, retome pelo fluxo oficial do /mednotes:fix-wiki."
+_TECHNICAL_GRAPH_CURATION_MARKERS = (
+    "med-link-graph-curator",
+    "collect-curator-outputs",
+    "eval-curator-batch",
+    "apply-curator-batch",
+    "vocabulary-curator-batch-plan",
+)
+
+
+class _FixWikiUserReportFieldModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
+
+
+class _FixWikiUserReportProjectionModel(BaseModel):
+    model_config = ConfigDict(extra="ignore", populate_by_name=True, validate_assignment=True)
+
+
+class _FsmProgressDisplayFields(_FixWikiUserReportProjectionModel):
+    status: StrictStr = ""
+    headline: StrictStr = ""
+    message: StrictStr = ""
+    detail: StrictStr = ""
+    count_label: StrictStr = ""
+    user_action: StrictStr = ""
+    resume_action: StrictStr = ""
+    can_continue_now: StrictBool | None = None
+
+
+class _FsmSnapshotDisplayFields(_FixWikiUserReportProjectionModel):
+    current_state: StrictStr = ""
+
+
+class _AgentCapabilitiesFields(_FixWikiUserReportProjectionModel):
+    continue_: StrictBool = Field(default=False, alias="continue")
+
+
+class _AgentControlFields(_FixWikiUserReportProjectionModel):
+    status: StrictStr = ""
+    capabilities: _AgentCapabilitiesFields = Field(default_factory=_AgentCapabilitiesFields)
+    effects: list[JsonValue] = Field(default_factory=list)
+
+
+class _AgentDirectiveFields(_FixWikiUserReportProjectionModel):
+    control: _AgentControlFields = Field(default_factory=_AgentControlFields)
+
+
+class _FsmReportsDisplayFields(_FixWikiUserReportProjectionModel):
+    summary: StrictStr = ""
+    public_report: WorkflowPublicReport
+
+
+class _FixWikiFsmReportRootFields(_FixWikiUserReportProjectionModel):
+    """Typed projection of the canonical FSM payload used by the user renderer."""
+
+    progress_view_model: JsonObject
+    state_machine_snapshot: JsonObject
+    reports: _FsmReportsDisplayFields
+    receipt: JsonObject
+    agent_directive: JsonObject
+    human_decision_packet: JsonObject | None = None
+
+
+class _DecisionOptionFields(_FixWikiUserReportFieldModel):
+    id: StrictStr = ""
+    label: StrictStr = ""
+
+
+class _RejectedAutomationFields(_FixWikiUserReportFieldModel):
+    kind: StrictStr = ""
+    reason: StrictStr = ""
+    reason_code: StrictStr = ""
+
+
+class _HumanDecisionPacketFields(_FixWikiUserReportFieldModel):
+    question: StrictStr = ""
+    public_summary: StrictStr = ""
+    options: list[_DecisionOptionFields] = Field(default_factory=list)
+    rejected_automations: list[_RejectedAutomationFields] = Field(default_factory=list)
+    resume_action: StrictStr = ""
+
+
+def _json_object(value: object) -> JsonObject:
+    return JsonObjectAdapter.validate_python(value)
+
+
+def _json_array(value: object) -> list[JsonValue]:
+    return JsonArrayAdapter.validate_python(value)
+
+
+def _field_payload(source: JsonObject, field_names: tuple[str, ...]) -> JsonObject:
+    payload: JsonObject = {}
+    for field_name in field_names:
+        if field_name in source:
+            payload[field_name] = source[field_name]
+    return payload
+
+
+def _json_array_field(source: JsonObject, field_name: str) -> list[JsonValue]:
+    if field_name not in source:
+        return []
+    return _json_array(source[field_name])
+
+
+def _object_field_payload(source: JsonObject, field_name: str, field_names: tuple[str, ...]) -> JsonObject:
+    if field_name not in source:
+        return {}
+    return _field_payload(_json_object(source[field_name]), field_names)
+
+
+def _decision_options(source: JsonObject) -> list[_DecisionOptionFields]:
+    return [
+        _DecisionOptionFields.model_validate(_field_payload(_json_object(item), ("id", "label")))
+        for item in _json_array_field(source, "options")
+    ]
+
+
+def _rejected_automations(source: JsonObject) -> list[_RejectedAutomationFields]:
+    return [
+        _RejectedAutomationFields.model_validate(_field_payload(_json_object(item), ("kind", "reason", "reason_code")))
+        for item in _json_array_field(source, "rejected_automations")
+    ]
+
+
+def _human_decision_packet_fields(source: JsonObject) -> _HumanDecisionPacketFields:
+    payload = _field_payload(source, ("question", "public_summary", "resume_action"))
+    payload["options"] = _decision_options(source)
+    payload["rejected_automations"] = _rejected_automations(source)
+    return _HumanDecisionPacketFields.model_validate(payload)
+
+
+def _human_decision_packet_has_data(packet: _HumanDecisionPacketFields) -> bool:
+    return bool(
+        packet.question
+        or packet.public_summary
+        or packet.options
+        or packet.rejected_automations
+        or packet.resume_action
+    )
+
+
+def render_fix_wiki_user_report(report: object) -> str:
+    """Render only the canonical FSM payload; legacy root reports are rejected."""
+
+    payload = _json_object(report)
+    schema = payload["schema"] if "schema" in payload else ""
+    if schema != "medical-notes-workbench.fix-wiki-fsm-result.v1":
+        raise ValueError("fix-wiki user report requires the canonical FSM result payload")
+    assert_fix_wiki_fsm_payload(payload)
+    return _render_fix_wiki_fsm_report(payload)
+
+
+def write_fix_wiki_user_report_v2(path: Path, payload: object) -> None:
+    """Write a compact human report without raw note bodies or textual diffs."""
+
+    atomic_write_text(path, render_fix_wiki_user_report(payload))
+
+
+def _render_fix_wiki_fsm_report(report: JsonObject) -> str:
+    root = _FixWikiFsmReportRootFields.model_validate(report)
+    progress = _FsmProgressDisplayFields.model_validate(root.progress_view_model)
+    snapshot = _FsmSnapshotDisplayFields.model_validate(root.state_machine_snapshot)
+    public_report = root.reports.public_report
+    agent_directive = _AgentDirectiveFields.model_validate(root.agent_directive)
+    control = agent_directive.control
+    can_continue_without_human = (
+        control.status == "waiting_agent"
+        and control.capabilities.continue_ is True
+        and bool(control.effects)
+    )
+    public_lines = [
+        _public_safe_report_line(_clean(line))
+        for line in public_report.lines
+        if line.strip()
+    ]
+    if not can_continue_without_human:
+        public_lines = [line for line in public_lines if not _mentions_automatic_continuation(line)]
+    reports_summary = _clean(root.reports.summary)
+    summary = _clean(public_report.headline or reports_summary or progress.headline or progress.message or "Conferência concluída.")
+    if not can_continue_without_human and _mentions_automatic_continuation(summary):
+        summary = public_lines[0] if public_lines else "Workflow aguardando condição externa para retomar pela rota oficial."
+    next_action = _public_next_action_from_report_lines(public_lines)
+    public_lines = [line for line in public_lines if not _is_public_next_action_line(line)]
+    progress_status = progress.status
+    count_label = _clean(progress.count_label)
+    lines: list[str] = [
+        "# Fix Wiki Report",
+        "",
+        "## Resumo",
+        "",
+        f"- {summary}",
+    ]
+    for line in public_lines:
+        if _looks_like_transient_mutation_line(line):
+            continue
+        if line != summary:
+            lines.append(f"- {line}")
+    if count_label:
+        lines.append(f"- progresso: {count_label}")
+    headline = _clean(progress.headline or progress.message)
+    detail = _clean(progress.detail)
+    if headline and headline != summary:
+        lines.append(f"- {headline}")
+    if detail and detail not in {summary, headline}:
+        lines.append(f"- detalhe: {detail}")
+    can_continue_now = progress.can_continue_now
+    current_state = _clean(snapshot.current_state)
+    if can_continue_now is False and not can_continue_without_human:
+        lines.append(f"- agora: {_waiting_line_for_state(progress_status=progress_status, current_state=current_state)}")
+    if can_continue_without_human and not any("continuar automaticamente" in line.casefold() for line in lines):
+        lines.append("- vou continuar automaticamente pela próxima etapa segura.")
+    if current_state == "waiting_for_external_quota":
+        lines.append("- estado: progresso preservado para retomada quando a cota voltar.")
+    if next_action:
+        lines.extend(["", "## Próxima Ação", "", f"- {next_action}"])
+    decision_packet = (
+        _human_decision_packet_fields(root.human_decision_packet)
+        if root.human_decision_packet is not None
+        else _HumanDecisionPacketFields()
+    )
+    if _human_decision_packet_has_data(decision_packet):
+        lines.extend(["", "## Decisão Necessária", ""])
+        lines.extend(_human_decision_packet_details(decision_packet))
+    objective = fix_wiki_primary_objective_summary(report)
+    if objective is not None:
+        lines.extend(
+            [
+                "",
+                "## Resultado Da Wiki",
+                "",
+                f"- Wiki: {objective.wiki_summary}",
+                f"- Mudanças reais: {objective.mutation_summary}",
+                f"- Grafo: {objective.graph_summary}",
+                f"- Notas Relacionadas: {objective.related_notes_summary}",
+            ]
+        )
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _clean(value: object) -> str:
+    if value is None:
+        raw = ""
+    elif isinstance(value, str):
+        raw = value
+    else:
+        raw = str(value)
+    text = raw.replace("\r", " ").replace("\n", " ").strip()
+    return text.replace("|", "\\|")
+
+
+def _public_safe_report_line(value: str) -> str:
+    prefix = "Próxima ação:"
+    if value.casefold().startswith(prefix.casefold()):
+        action = value[len(prefix):].strip()
+        safe_action = _public_safe_next_action(action)
+        return f"{prefix} {safe_action}" if safe_action else ""
+    return _public_safe_next_action(value) if _is_technical_graph_curation_action(value) else value
+
+
+def _is_public_next_action_line(value: str) -> bool:
+    return value.casefold().startswith("próxima ação:")
+
+
+def _public_next_action_from_report_lines(lines: list[str]) -> str:
+    prefix = "Próxima ação:"
+    for line in lines:
+        if line.casefold().startswith(prefix.casefold()):
+            return _public_safe_next_action(_clean(line[len(prefix):]))
+    return ""
+
+
+def _public_safe_next_action(value: str) -> str:
+    if not value:
+        return ""
+    if _is_technical_graph_curation_action(value):
+        return _PUBLIC_GRAPH_CURATION_ACTION
+    return value
+
+
+def _is_technical_graph_curation_action(value: str) -> bool:
+    folded = value.casefold()
+    return any(marker in folded for marker in _TECHNICAL_GRAPH_CURATION_MARKERS)
+
+
+def _looks_like_transient_mutation_line(value: str) -> bool:
+    return bool(_TRANSIENT_MUTATION_LINE_RE.search(value))
+
+
+def _mentions_automatic_continuation(value: str) -> bool:
+    return "continuar automaticamente" in value.casefold()
+
+
+def _waiting_line_for_state(*, progress_status: str, current_state: str) -> str:
+    if progress_status == "waiting_human":
+        return "aguardando decisão segura antes de continuar."
+    if progress_status == "waiting_external" or current_state == "waiting_for_external_quota":
+        return "aguardando condição externa antes de continuar."
+    return "aguardando a próxima etapa oficial antes de continuar."
+
+
+def _human_decision_packet_details(packet: _HumanDecisionPacketFields) -> list[str]:
+    if not _human_decision_packet_has_data(packet):
+        return []
+    out: list[str] = []
+    question = _clean(packet.question or packet.public_summary)
+    if question:
+        out.append(f"- pergunta: {question}")
+    option_labels = [
+        _clean(option.label or option.id)
+        for option in packet.options[:8]
+        if option.label or option.id
+    ]
+    if option_labels:
+        out.append(f"- opções fechadas: {', '.join(option_labels)}")
+    if packet.rejected_automations:
+        out.append("- automações rejeitadas:")
+        for item in packet.rejected_automations[:8]:
+            kind = _clean(item.kind)
+            reason = _clean(item.reason or item.reason_code)
+            out.append(f"  - {kind}: {reason}")
+    else:
+        out.append("- possível_bug_ux: decisão humana sem automações rejeitadas registradas.")
+    if packet.resume_action:
+        out.append(f"- retomada: {_PUBLIC_HUMAN_DECISION_RESUME}")
+    return out