mednotes-opencode 0.1.0

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

@@ -0,0 +1,510 @@
+"""Registry for workflow blocker decisions."""
+from __future__ import annotations
+
+from mednotes.domains.wiki.contracts.workflow_outcomes import DecisionEvidence, DecisionKind, WorkflowDecision
+from mednotes.kernel.blockers import BlockerEntryModel
+
+
+class BlockerRegistryError(KeyError):
+    """Raised when workflow code emits an unregistered blocker."""
+
+
+BlockerEntry = BlockerEntryModel
+
+
+def _entry(
+    code: str,
+    *,
+    owner_phase: str,
+    decision: DecisionKind,
+    safe: bool,
+    human_packet: bool = False,
+    public_label: str,
+    public_explanation: str,
+    developer_explanation: str,
+    test_fixture: str,
+) -> BlockerEntry:
+    return BlockerEntryModel(
+        code=code,
+        owner_phase=owner_phase,
+        default_decision=decision,
+        safe_to_continue_batch=safe,
+        requires_human_packet=human_packet,
+        public_label=public_label,
+        public_explanation=public_explanation,
+        developer_explanation=developer_explanation,
+        test_fixture=test_fixture,
+    )
+
+
+def _entries(
+    codes: list[str],
+    *,
+    owner_phase: str,
+    decision: DecisionKind,
+    safe: bool,
+    human_packet: bool = False,
+    public_label: str,
+    public_explanation: str,
+    developer_explanation: str,
+    test_fixture: str,
+) -> dict[str, BlockerEntry]:
+    return {
+        code: _entry(
+            code,
+            owner_phase=owner_phase,
+            decision=decision,
+            safe=safe,
+            human_packet=human_packet,
+            public_label=public_label,
+            public_explanation=public_explanation,
+            developer_explanation=developer_explanation,
+            test_fixture=test_fixture,
+        )
+        for code in codes
+    }
+
+
+BLOCKER_REGISTRY: dict[str, BlockerEntry] = {}
+
+BLOCKER_REGISTRY.update(
+    _entries(
+        [
+            "canonical_merge_required",
+            "human_decision_required",
+            "human_decision_required.ambiguous_canonical_target",
+            "image_metadata_conflict",
+            "taxonomy_resolution_required",
+        ],
+        owner_phase="human_decision",
+        decision="ask_human",
+        safe=False,
+        human_packet=True,
+        public_label="Decisao humana necessaria",
+        public_explanation="A escolha altera organizacao editorial ou evidencia e precisa de contexto humano.",
+        developer_explanation="Human route allowed only with typed human_decision_packet and rejected automation evidence.",
+        test_fixture="tests/test_workflow_outcomes.py",
+    )
+)
+
+BLOCKER_REGISTRY.update(
+    _entries(
+        [
+            "anki_model_validation_failed",
+            "config_encoding_invalid",
+            "flashcards_prepare_blocked",
+            "flashcards_source_stale",
+            "invalid_flashcard_candidate_batch",
+            "invalid_obsidian_deeplink",
+            "markdown_index_missing",
+            "markdown_index_stale",
+            "markdown_runtime_missing",
+            "markdown_runtime_stale",
+            "node_runtime_missing",
+            "node_runtime_stale",
+            "restore_conflict",
+            "stale_restore_point",
+            "alias_projection.stale_note_hash",
+            "alias_projection.blocked_operations",
+            "alias_projection.invalid_plan_schema",
+            "alias_projection_blocked",
+            "agent_behavior_report_would_overwrite_baseline",
+            "agent_final_report_contract_violation",
+            "atomicity_split_required",
+            "apply_curator_batch_validation_error",
+            "batch_state_mismatch",
+            "coverage_invalid",
+            "coverage_path_missing",
+            "contextual_alias_disambiguation_failed",
+            "curator_output_hash_mismatch",
+            "curator_output_manifest.missing_sha256",
+            "curator_prompt_eval.blocked",
+            "curator_prompt_eval.inconsistent_report",
+            "curator_prompt_eval.invalid_status",
+            "curator_prompt_eval.needs_review",
+            "curator_prompt_eval_options_conflict",
+            "curator_prompt_eval_required",
+            "curator_prompt_eval_skip_not_allowed",
+            "deferred_work_item_blocked",
+            "deferred_work_item_not_pending",
+            "deferred_work_item_read_failed",
+            "deferred_work_item_source_mismatch",
+            "deferred_work_item_stale",
+            "deferred_work_item_update_failed",
+            "deferred_work_item_update_missed",
+            "diagnosis_blocked",
+            "diagnosis_blocked_after_vocabulary_repair",
+            "destination_exists",
+            "destination_inside_source",
+            "diagnosis_required",
+            "dry_run_receipt_required",
+            "dry_run_receipt_invalid",
+            "new_taxonomy_leaf_requires_dry_run_authorization",
+            "duplicate_obsidian_target",
+            "duplicate_target",
+            "duplicate_destination",
+            "fix_wiki_failed",
+            "graph_blockers",
+            "hygiene_errors",
+            "link_plan_blocked",
+            "linker_blocked",
+            "manifest_mismatch",
+            "manifest_invalid",
+            "meaning_claim_invalid",
+            "markdown_query_index_unavailable",
+            "missing_or_invalid_artifact_manifest",
+            "missing_or_invalid_note_plan",
+            "note_plan_invalid",
+            "note_plan_v2_required",
+            "orchestrator_required",
+            "preconditions_failed",
+            "process_chats_linker_blocked",
+            "provenance_gap",
+            "publish_receipt_invalid",
+            "publish_state_blocked",
+            "reference_repair_required",
+            "related_notes",
+            "related_notes_blocked",
+            "related_notes_edge_invalid",
+            "related_notes_edges_invalid",
+            "related_notes_export_contract_invalid",
+            "related_notes_export_invalid",
+            "related_notes_export_invalid_json",
+            "related_notes_export_missing",
+            "related_notes_export_schema_invalid",
+            "related_notes_export_still_stale",
+            "related_notes_export_stale",
+            "related_notes_hash_migration_write_failed",
+            "related_notes_hash_mismatch",
+            "related_notes_note_path_invalid",
+            "related_notes_notes_invalid",
+            "related_notes_recovery_not_applicable",
+            "related_notes_recovery_blocked",
+            "related_notes_revalidation_failed",
+            "related_notes_vault_mismatch",
+            "requires_llm_rewrite",
+            "root_note",
+            "retry_requested",
+            "semantic_ingestion.atomicity_signal_required",
+            "semantic_ingestion.integrity_conflict",
+            "semantic_ingestion.invalid_atomic_status",
+            "semantic_ingestion.meaning_canonical_conflict",
+            "semantic_ingestion.meaning_note_conflict",
+            "semantic_ingestion.stale_note_hash",
+            "semantic_ingestion.validation_error",
+            "source_missing",
+            "source_not_directory",
+            "stale_diagnosis",
+            "stale_receipt",
+            "stale_fix_wiki_plan",
+            "style_rewrite_required",
+            "taxonomy_action_required",
+            "taxonomy_blocked",
+            "taxonomy_plan_blocked",
+            "triager_eval_failed",
+            "triager_eval_invalid",
+            "triager_eval_required",
+            "triager_eval_stale",
+            "unmapped_top_level_dir",
+            "validation_errors",
+            "validation_failed",
+            "vocabulary_bootstrap_required",
+            "vocabulary_db_missing",
+            "vocabulary_map.unresolved_surfaces_without_meanings",
+            "vocabulary_map_blocked",
+            "vocabulary_queue_inconsistent",
+            "vocabulary_recovery_backup_exists",
+            "vocabulary_recovery_plan_blocked",
+            "vocabulary_recovery_plan_required",
+            "vocabulary_recovery_plan_stale",
+            "vocabulary_recovery_receipt_required",
+            "vocabulary_recovery_receipt_unwritable",
+            "vocabulary_semantic_ingestion_pending",
+            "vocabulary_semantic_ingestion_stale",
+            "vocabulary_semantic_repair_blocked",
+            "vocabulary_schema_drift",
+            "write_errors",
+        ],
+        owner_phase="workflow_recovery",
+        decision="auto_plan",
+        safe=True,
+        public_label="Recuperacao automatica planejavel",
+        public_explanation="O workflow deve regenerar, reconciliar ou validar artefatos antes de continuar.",
+        developer_explanation="Recoverable blocker: route to the official plan/diagnosis/recovery step, not ask_human.",
+        test_fixture="tests/test_workflow_blocker_scanner.py",
+    )
+)
+
+BLOCKER_REGISTRY.update(
+    _entries(
+        [
+            "provenance.legacy_chat_original_footer",
+            "provenance.sources_section_missing",
+        ],
+        owner_phase="provenance_backfill",
+        decision="auto_fix",
+        safe=True,
+        public_label="Correcao automatica de proveniencia",
+        public_explanation="A nota tem proveniencia recuperavel e o workflow pode normalizar a estrutura.",
+        developer_explanation="Recoverable provenance shape: route through sources backfill/fix-wiki before continuing.",
+        test_fixture="tests/test_wiki_provenance_style.py",
+    )
+)
+
+BLOCKER_REGISTRY.update(
+    _entries(
+        [
+            "no_delta_to_merge",
+            "related_notes_export_only_unsafe_for_changed_notes",
+            "vocabulary_bootstrap_preview",
+            "vocabulary_map.direct_policy_on_ambiguous_surface",
+        ],
+        owner_phase="workflow_deferral",
+        decision="auto_defer",
+        safe=True,
+        public_label="Adiamento automatico seguro",
+        public_explanation="O workflow pode continuar de forma conservadora sem pedir escolha manual.",
+        developer_explanation="Conservative skip/defer route is safer than ask_human for this blocker.",
+        test_fixture="tests/test_workflow_blockers.py",
+    )
+)
+
+BLOCKER_REGISTRY.update(
+    _entries(
+        [
+            "apply_plan_already_exists",
+            "blocked_branch_confirmation_required",
+            "branch_confirmation_required",
+            "flashcards_preview_confirmation_required",
+            "github_cli_missing",
+            "github_login_required",
+            "github_remote_ambiguous",
+            "github_remote_confirmation_required",
+            "github_remote_missing",
+            "github_remote_pending",
+            "history_restore_confirmation_required",
+            "link_apply_confirmation_required",
+            "link_related_apply_confirmation_required",
+            "publish_confirmation_required",
+            "plan_already_exists",
+            "preview_ready_for_human_choice",
+            "restore_mutates_resources",
+            "restore_preview_already_exists",
+            "restore_preview_requires_choice",
+            "vault_mutation_requires_confirmation",
+            "writes_anki_and_vault_tag",
+            "blocks_fix_wiki",
+            "blocks_reference_repair",
+            "no_unambiguous_target",
+            "non_main_branch",
+            "plan_needs_choice",
+            "plan_needs_target",
+            "unsafe_choice",
+            "unsafe_editorial_choice",
+        ],
+        owner_phase="public_workflow_human_decision",
+        decision="ask_human",
+        safe=False,
+        human_packet=True,
+        public_label="Confirmacao humana necessaria",
+        public_explanation="A proxima etapa altera vault, Anki, historico ou politica local e precisa de confirmacao fechada.",
+        developer_explanation="Public FSM route must expose a typed human_decision_packet/resume_action, not a textual blocker.",
+        test_fixture="tests/test_workflow_blocker_scanner.py",
+    )
+)
+
+BLOCKER_REGISTRY.update(
+    _entries(
+        [
+            "agent_session_transcript_unreadable",
+            "agent_tool_contract_violation",
+            "agy_runtime_log_unavailable",
+            "agy_specialist_invocation_evidence_missing",
+            "agy_specialist_model_evidence_mismatch",
+            "agy_specialist_model_evidence_missing",
+            "agy_transcript_evidence_missing",
+            "architect_coverage_invalid",
+            "architect_note_validation_failed",
+            "architect_output_contract_invalid",
+            "architect_output_missing",
+            "architect_output_plan_mismatch",
+            "architect_plan_contract_invalid",
+            "architect_raw_file_missing",
+            "architect_work_item_missing",
+            "blocked",
+            "chats.shape_invalid",
+            "contract_gap.missing_error_context",
+            "contract_gap.missing_next_action",
+            "curator_prompt_eval.dev_escape_disabled",
+            "curator_prompt_eval.dev_escape_ignored",
+            "environment_blocker.windows_path_or_venv",
+            "OSError",
+            "anki_unavailable",
+            "force_diagnose_requires_diagnose",
+            "history_blocked",
+            "history_failed",
+            "invalid_linker_deferral",
+            "link_artifact_contract_invalid",
+            "link_diagnosis_contract_invalid",
+            "linker_mode_required",
+            "llm_disambiguation_failed",
+            "llm_disambiguation_invalid_response",
+            "obsidian_cli_timeout",
+            "obsidian_cli_unavailable",
+            "obsidian_not_ready",
+            "opencode_specialist_model_evidence_missing",
+            "opencode_specialist_model_fallback_forbidden",
+            "opencode_specialist_raw_content_contract_violation",
+            "opencode_specialist_task_metadata_invalid",
+            "opencode_specialist_task_metadata_mismatch",
+            "opencode_specialist_task_metadata_missing",
+            "opencode_specialist_task_metadata_placeholder",
+            "paths_missing",
+            "process_chats_publish_quota",
+            "related_notes_export_command_missing",
+            "related_notes_export_contains_private_payload",
+            "related_notes_headless_api_key_missing",
+            "related_notes_headless_plugin_settings_invalid",
+            "related_notes_headless_plugin_settings_missing",
+            "related_notes_headless_quota_exhausted",
+            "related_notes_headless_time_budget_exhausted",
+            "related_notes_plugin_unavailable",
+            "related_notes_apply_blocked",
+            "related_notes_convergence_not_reached",
+            "related_notes_export_recovery_blocked",
+            "related_notes_export_recovery_contract_invalid",
+            "related_notes_preview_blocked",
+            "related_notes_reindex_command_missing",
+            "related_notes_reindex_failed",
+            "receipt_path_exists",
+            "subagent_plan_attestation_invalid",
+            "subagent_plan_attestation_required",
+            "subagent_output_contract.invalid",
+            "specialist_model_metadata_missing",
+            "specialist_model_unavailable",
+            "specialist_model_quota_exhausted",
+            "specialist_runner_command_failed",
+            "specialist_runner_harness_unsupported",
+            "specialist_runner_policy_config_invalid",
+            "specialist_runner_timeout",
+            "specialist_runner_untrusted_gemini_binary",
+            "specialist_workspace_cleanup_failed",
+            "specialist_model_metadata_missing_after_timeout_output",
+            "specialist_task_run_receipt_attestation_invalid",
+            "specialist_task_run_receipt_invalid",
+            "style_rewrite_agent_contract_violation",
+            "style_rewrite_manifest_invalid",
+            "style_rewrite_manifest_required",
+            "style_rewrite_output_attestation_hash_mismatch",
+            "style_rewrite_output_attestation_invalid",
+            "style_rewrite_output_attestation_required",
+            "style_rewrite_output_hash_mismatch",
+            "style_rewrite_output_missing",
+            "style_rewrite_output_receipt_hash_mismatch",
+            "style_rewrite_output_receipt_invalid",
+            "style_rewrite_output_receipt_required",
+            "style_rewrite_plan_contract_invalid",
+            "style_rewrite_plan_missing",
+            "style_rewrite_model_provenance_unverified",
+            "style_rewrite_specialist_model_required",
+            "style_rewrite_stale_target_hash",
+            "style_rewrite_still_requires_rewrite",
+            "style_rewrite_target_missing",
+            "trigger_context_apply_not_allowed",
+            "related_notes_quota_wait",
+            "unsupported_by_policy",
+            "unsupported_host_or_policy_gap",
+            "ValidationError",
+            "vault_guard_required",
+            "version_control_safety_evidence_missing",
+            "wait_external.publish_quota",
+            "wait_external.specialist_capacity",
+            "vocabulary_db_mismatch",
+            "vocabulary_db_unconfigured",
+            "vocabulary_schema_drift_unsupported",
+            "wiki_dir_missing",
+            "wiki_path_missing",
+            "workflow_blocked",
+            "workflow_effect_blocked",
+            "workflow_effect_failed",
+        ],
+        owner_phase="operational_guardrail",
+        decision="hard_block",
+        safe=False,
+        public_label="Bloqueio operacional",
+        public_explanation="O workflow deve parar ate o pre-requisito operacional ficar seguro.",
+        developer_explanation="External, security, environment, or contract blocker; do not ask_human as a fallback.",
+        test_fixture="tests/test_workflow_guardrails_contract.py",
+    )
+)
+
+BLOCKER_REGISTRY.update(
+    _entries(
+        [
+            "failed",
+            "flashcards_apply_failed",
+            "flashcards_prepare_failed",
+            "io_error_rollback_performed",
+            "linker_error",
+            "related_notes_headless_embedding_failed",
+            "vocabulary_recovery_receipt_finalization_failed",
+            "vocabulary_sqlite_integrity_error",
+        ],
+        owner_phase="workflow_failure",
+        decision="failed",
+        safe=False,
+        public_label="Falha operacional",
+        public_explanation="O workflow falhou depois de uma tentativa operacional e precisa de inspecao ou retry seguro.",
+        developer_explanation="Failure route: report failure context and avoid converting IO/integrity failures into ask_human.",
+        test_fixture="tests/test_med_chat_processor.py",
+    )
+)
+
+BLOCKER_REGISTRY.update(
+    _entries(
+        [
+            "taxonomy_decision_required",
+        ],
+        owner_phase="taxonomy",
+        decision="ask_human",
+        safe=False,
+        human_packet=True,
+        public_label="Decisao de taxonomia necessaria",
+        public_explanation="A movimentacao de taxonomia precisa de aprovacao humana antes de aplicar.",
+        developer_explanation="Taxonomy approval requires a typed human_decision_packet before crossing workflow boundaries.",
+        test_fixture="tests/test_path_contract_models.py",
+    )
+)
+
+
+def blocker_entry(code: str) -> BlockerEntry:
+    try:
+        return BLOCKER_REGISTRY[code]
+    except KeyError as exc:
+        raise BlockerRegistryError(f"unknown blocker code: {code}") from exc
+
+
+def decision_for_code(
+    code: str,
+    *,
+    phase: str,
+    public_summary: str,
+    developer_summary: str,
+    next_action: str,
+) -> WorkflowDecision:
+    entry = blocker_entry(code)
+    return WorkflowDecision(
+        kind=entry.default_decision,
+        phase=phase,
+        reason_code=code,
+        public_summary=public_summary or entry.public_explanation,
+        developer_summary=developer_summary or entry.developer_explanation,
+        evidence=[
+            DecisionEvidence(
+                summary=entry.public_explanation,
+                technical_code=code,
+                source=entry.owner_phase,
+            )
+        ],
+        next_action=next_action,
+    )