mednotes-opencode 0.1.0

package/.opencode/mednotes/docs/flashcard-ingestion.md

@@ -0,0 +1,278 @@
+# Flashcard Ingestion Design
+
+Doc e fonte unica de regras locais de ingestao p/ flashcards medicos no Anki. Metodologia vive em `${extensionPath}/docs/anki-mcp-twenty-rules.md`, copia operacional do prompt MCP `/twenty_rules` do servidor `anki-mcp`. Copia local existe pq subagents Gemini CLI nao chamam slash prompts MCP. Doc define decisoes de design da extensao Medical Notes Workbench.
+
+## Contrato Runtime
+
+`/flashcards` e FSM-first. Agentes e consumidores devem orientar o fluxo por
+`progress_view_model`, `state_machine_snapshot`, `decision`, `receipt`,
+`reports` e `agent_directive.control`, nao por conclusoes soltas do agente.
+Quando existir, `diagnostic_context` e apenas evidencia opcional para explicar
+problema, retry, bloqueio ou investigacao; ele nao escolhe rota nem autoriza
+efeito.
+
+## Modelos Anki Gerenciados
+
+Skill mantem **dois** note types no Anki, provisionados via Anki MCP de `${extensionPath}/docs/anki-templates/`:
+
+- `Medicina` (Q&A, `isCloze: false`) — campos `Frente`, `Verso`, `Verso Extra`, `Obsidian`. Cards pergunta/resposta classica.
+- `Medicina Cloze` (cloze, `isCloze: true`) — campos `Texto`, `Verso Extra`, `Obsidian`. Campo `Texto` carrega `{{c1::...}}`, `{{c2::...}}`. Um card por grupo de cloze.
+
+**Roteamento por card:** subagent decide modelo por candidato. Use `Medicina Cloze` p/ definicao/fato encadeado/enumeracao curta (Twenty Rules #5, #9). Use `Medicina` p/ pergunta com resposta atomica. Cada `candidate_card` deve declarar `note_model`.
+
+**Provisao dos modelos:** antes de gravar, skill chama `mcp_anki-mcp_modelNames` + `mcp_anki-mcp_modelFieldNames` e roda:
+
+```bash
+uv run python ${extensionPath}/scripts/mednotes/flashcards/install_models.py ensure --existing - --output -
+```
+
+JSON resultante traz lista `actions` com `mcp_anki-mcp_createModel` (modelo ausente) ou `mcp_anki-mcp_updateModelTemplates` + `mcp_anki-mcp_updateModelStyling` (HTML/CSS divergiu). Se modelo aparecer como `incompatible` (mesmo nome, campos diferentes), pare e peca usuario apagar/renomear no Anki Desktop.
+
+Arquivos HTML/CSS em `${extensionPath}/docs/anki-templates/` sao fonte de verdade. Nao edite modelos no Anki Desktop — alteracoes sao sobrescritas no proximo run.
+
+## Regras De Conteúdo Para Cards Bonitos
+
+Templates dao consistencia visual; conteudo limpo e responsabilidade da skill. Aplique sempre:
+
+- **Frente Q&A:** pergunta atomica, ate 120 chars. Sem ponto-final desnecessario, sem prefixo "Pergunta:".
+- **Verso Q&A:** 1-2 frases curtas, direto. Nao repita pergunta, nao comece com "A resposta e".
+- **Verso Extra (ambos):** raciocinio, contexto, mnemonicos, fontes curtas. Comece com `\n\n` (texto puro) ou `<br><br>` (HTML). Use bullets `<ul><li>` ou `-`. Nunca repita Verso/cloze.
+- **Cloze (`Texto`):** enunciado fluente. Max 2-3 grupos `{{cN::...}}` por card. Cada cloze = unidade atomica; nunca paragrafo inteiro. Mantenha contexto suficiente p/ leitura com sentido.
+- **Obsidian:** deeplink copiado do manifest tipado da fonte. Dentro de vault
+  confiavel, prefira `obsidian://open?vault=Wiki_Medicina&file=Cardio%2FPonte.md`
+  com path POSIX relativo ao vault. Fora de vault confiavel, use fallback de
+  path real como
+  `obsidian://open?path=%2FUsers%2Fleo%2FWiki%20Medicina%2FCardio%2FPonte.md`.
+  Template renderiza como botao "Abrir no Obsidian".
+- **Sem markdown solto:** evite headings (`#`, `##`), negrito Markdown (`**...**`), codigo com crase. Use HTML p/ enfase (`<strong>`, `<em>`, `<code>`); Anki nao converte Markdown.
+
+## Especificacoes De Design
+
+1. Hierarquia de decks: reproduza estrutura de diretorios do Obsidian como subdecks no Anki.
+
+   Exemplo:
+
+   ```text
+   Wiki_Medicina/Cardiologia/Ponte_Miocardica.md
+   -> Wiki_Medicina::Cardiologia::Ponte_Miocardica
+   ```
+
+   Para arquivos em `Wiki_Medicina`, use `Wiki_Medicina` como raiz, preserve diretorios intermediarios, nome do arquivo sem `.md` como folha.
+
+   Nao achate hierarquia. Se `mcp_anki-mcp_createDeck` recusar mais de dois niveis, tente criar cards diretamente no deck completo com `mcp_anki-mcp_addNotes`/`mcp_anki-mcp_addNote`; se ainda recusar, reporte falha sem trocar deck.
+
+2. Tags Anki: nao adicionar tags. Omita `tags` ou envie lista vazia. Tags Obsidian podem selecionar notas mas nao viram tags Anki.
+
+3. Formatacao do campo: antes de inserir em `Verso Extra`, adicione espaco visual no inicio — `\n\n` (texto puro) ou `<br><br>` (HTML).
+
+4. Campo de origem: todo card de nota Markdown usa o deeplink do
+   `FlashcardSourceManifest`. O agente copia `fields.Obsidian` do manifest ou
+   deixa vazio para o pipeline tipado preencher; ele nunca fabrica uma URI.
+
+   ```bash
+   uv run python ${extensionPath}/scripts/mednotes/obsidian_note_utils.py deeplink <nota.md>
+   ```
+
+   O comando acima e utilitario tecnico para diagnostico/geracao do manifest;
+   nao substitui o manifest tipado. Dentro de vault, o link preferido e
+   `obsidian://open?vault=Wiki_Medicina&file=Cardio%2FPonte.md`, com path POSIX
+   vault-relativo. Fora de vault confiavel, o fallback e
+   `obsidian://open?path=%2FUsers%2Fleo%2FWiki%20Medicina%2FCardio%2FPonte.md`,
+   usando path real resolvido. Nao dependa da Obsidian CLI p/ extrair esse link.
+
+   Resolver pode inferir raiz do vault por `--vault-root`, `[paths].wiki_dir` em
+   `~/.gemini/medical-notes-workbench/config.toml`, compatibilidade
+   (`MED_WIKI_DIR`/config legado) ou diretorio `.obsidian` ancestral p/
+   preencher metadata (`vault_root`, `vault_relative_path`), deck e deeplink
+   preferido. `--vault-file` continua existindo como compatibilidade tecnica,
+   mas o padrao de manifest dentro do vault ja prefere `vault=...&file=...`.
+
+5. Marcacao da nota-fonte: apos pelo menos um card criado com sucesso, marque apenas essa nota com tag Obsidian `anki` via:
+
+   ```bash
+   uv run python ${extensionPath}/scripts/mednotes/obsidian_note_utils.py add-tag --tag anki <nota.md>
+   ```
+
+   Para desfazer:
+
+   ```bash
+   uv run python ${extensionPath}/scripts/mednotes/obsidian_note_utils.py remove-tag --tag anki <nota.md>
+   ```
+
+   Nao marque notas sem cards criados. Em sucesso parcial, marque so arquivos com pelo menos um card aceito.
+
+## Regra De Base De Conhecimento
+
+`/twenty_rules` sem namespace e reservado para prompt MCP `twenty_rules` do servidor global `anki-mcp`. Extensao nao declara outro Anki MCP no manifest (evita duplicacao com `~/.gemini/settings.json`) e nao cria comando local `/twenty_rules` (evita colisao).
+Referencia upstream: `@ankimcp/anki-mcp-server/dist/mcp/primitives/essential/prompts/twenty-rules.prompt/content.md`.
+Agente carrega metodologia por `read_file` em `${extensionPath}/docs/anki-mcp-twenty-rules.md`.
+Comando `/flashcards` aceita arquivo, multiplos arquivos, diretorios, globs, filtros por tag Obsidian e instrucoes em linguagem natural.
+Tag Obsidian `anki` e reservada p/ notas que ja geraram cards com sucesso.
+
+Ao receber `/flashcards <escopo>`, agente deve:
+
+1. Resolver escopo com `flashcard_sources.py resolve --scope "<escopo>" --dry-run`.
+2. Usar `read_file` p/ extrair conteudo de cada arquivo em `manifest.notes[].path`.
+3. Formular cards candidatos sem gravar no Anki.
+4. Preparar plano com `flashcard_pipeline.py prepare`.
+5. No modo padrao, mostrar cards no terminal e pedir confirmacao antes de gravar. Criacao direta so permitida quando usuario pedir explicitamente.
+6. Usar exclusivamente conteudo lido desses arquivos como base (o "O QUE" dos flashcards).
+7. Aplicar rigorosamente `${extensionPath}/docs/anki-mcp-twenty-rules.md` e especificacoes deste doc como "COMO".
+
+Nao use conhecimento externo p/ acrescentar fatos. Conhecimento medico geral pode ser usado apenas p/ entender, segmentar e redigir melhor o conteudo ja presente.
+
+## Resolucao De Escopo Para `/flashcards`
+
+1. Use resolver deterministico antes de ler notas ou chamar subagent:
+
+   ```bash
+   uv run python ${extensionPath}/scripts/mednotes/flashcard_sources.py resolve --scope "<argumentos>" --dry-run --skip-tag anki
+   ```
+
+   Retorna JSON com `schema`, `summary`, `scope`, `notes`, `skipped_notes` e `warnings`.
+
+2. Arquivos explicitos, diretorios e globs: resolver inclui apenas Markdown (`.md`/`.markdown`), ignora `dist/`, `.git/`, caches, anexos, imagens e nao-Markdown.
+3. Tags Obsidian: resolver filtra por frontmatter `tags`/`tag` e hashtags inline. Tag e criterio de selecao, exceto marcacao pos-sucesso `anki`.
+4. Pastas em linguagem natural: p/ frases como `notas com tag #revisar na
+   pasta Cardiologia`, resolver procura pasta dentro de `--vault-root`, `--wiki-dir` ou `wiki_dir` de `~/.gemini/medical-notes-workbench/config.toml`; env/config legado aceitos como compatibilidade.
+5. Escopo ambiguo: se resolver falhar pedindo raiz, pergunte qual vault/wiki e rode com `--vault-root <pasta>` ou `--wiki-dir <pasta>`.
+6. Notas ja processadas: por padrao, `/flashcards` deve passar `--skip-tag anki` p/ evitar duplicacao. Se usuario pedir refazer/regenerar, rode sem esse filtro. Notas puladas aparecem em `skipped_notes` com `skip_reason: "skip_tag"` e `skip_tags: ["anki"]`.
+7. Manifest por nota: cada item em `notes` traz `path`, `deck`, `deeplink`, `vault_relative_path`, `link_mode`, `tags`, `already_marked_anki`, `content_sha256`, `line_count` e `heading_count`. Use esses campos como fonte operacional de deck/link; leia conteudo factual separadamente com `read_file`.
+8. Lotes grandes: se `summary.requires_confirmation` for verdadeiro, mostre previa e peca confirmacao antes de formular/gravar. Para previa textual:
+
+   ```bash
+   uv run python ${extensionPath}/scripts/mednotes/flashcard_sources.py preview --scope "<argumentos>" --dry-run --skip-tag anki
+   ```
+
+   `preview` usa mesma resolucao de `resolve` mas emite texto humano em vez de JSON.
+
+## Manifest De Cards Candidatos E Idempotencia
+
+Apos resolver fontes e ler arquivos com `read_file`, agente formula cards candidatos antes de chamar Anki MCP. Formato minimo:
+
+```json
+{
+  "source_manifest": {},
+  "preferred_models": {
+    "qa": "Medicina",
+    "cloze": "Medicina Cloze"
+  },
+  "models": {
+    "Medicina": ["Frente", "Verso", "Verso Extra", "Obsidian"],
+    "Medicina Cloze": ["Texto", "Verso Extra", "Obsidian"]
+  },
+  "candidate_cards": [
+    {
+      "source_path": "/path/nota.md",
+      "source_content_sha256": "sha256-da-nota",
+      "deck": "Wiki_Medicina::Cardiologia::Ponte_Miocardica",
+      "note_model": "Medicina",
+      "fields": {
+        "Frente": "...",
+        "Verso": "...",
+        "Verso Extra": "\n\n...",
+        "Obsidian": "obsidian://open?vault=Wiki_Medicina&file=Cardiologia%2FPonte_Miocardica.md"
+      }
+    },
+    {
+      "source_path": "/path/nota.md",
+      "source_content_sha256": "sha256-da-nota",
+      "deck": "Wiki_Medicina::Cardiologia::Ponte_Miocardica",
+      "note_model": "Medicina Cloze",
+      "fields": {
+        "Texto": "A {{c1::ponte miocárdica}} envolve mais frequentemente a {{c2::DA}}.",
+        "Verso Extra": "\n\nDescrita pela primeira vez em 1737.",
+        "Obsidian": "obsidian://open?vault=Wiki_Medicina&file=Cardiologia%2FPonte_Miocardica.md"
+      }
+    }
+  ]
+}
+```
+
+`preferred_model` (singular) ainda aceito como atalho legado quando todos cards sao Q&A. Para fluxo padrao, use `preferred_models` com duas chaves.
+
+Antes de gravar, filtre duplicados locais:
+
+```bash
+uv run python ${extensionPath}/scripts/mednotes/flashcard_index.py check --candidates <candidate_cards.json>
+```
+
+Grave somente `new_cards`. Apos Anki MCP aceitar, registre apenas cards aceitos:
+
+```bash
+uv run python ${extensionPath}/scripts/mednotes/flashcard_index.py record --accepted <accepted_cards.json>
+```
+
+Indice padrao em `~/.gemini/medical-notes-workbench/FLASHCARDS_INDEX.json`, sobrescrito por `MED_FLASHCARDS_INDEX` ou `--index`. Tag Obsidian `anki` continua como marcador visual/filtro; idempotencia real passa pelo indice local.
+
+Para fluxo completo, prefira orquestrador deterministico:
+
+```bash
+uv run python ${extensionPath}/scripts/mednotes/flashcard_pipeline.py prepare --input <run.json>
+uv run python ${extensionPath}/scripts/mednotes/flashcard_pipeline.py apply --input <accepted-run.json>
+```
+
+`prepare` combina validacao de modelo, status de fontes alteradas, checagem de duplicidade, queries de `findNotes` e payload `anki_notes` p/ `addNotes`. `apply` registra cards aceitos e devolve relatorio estruturado.
+
+Payload de `prepare` precisa incluir campos de modelo capturados do Anki MCP. Em modo candidato, subagent chama `mcp_anki-mcp_modelNames` + `mcp_anki-mcp_modelFieldNames`, escolhe `preferred_model` quando compativel e devolve `models` como `{modelo: [campos...]}` ou lista `{name, fields}`. Em modo de gravacao, use `anki_find_queries` do plano p/ rodar `mcp_anki-mcp_findNotes` antes de `addNotes`; cards encontrados no Anki sao pulados como duplicados.
+
+## Preview Antes Da Escrita
+
+Comportamento padrao de `/flashcards` e preview-first: apos formular `candidate_cards` e rodar `flashcard_pipeline.py prepare`, mostre cards no terminal e aguarde confirmacao antes de chamar `mcp_anki-mcp_addNotes`/`mcp_anki-mcp_addNote`.
+
+Use plano retornado por `prepare` como entrada:
+
+```bash
+uv run python ${extensionPath}/scripts/mednotes/flashcard_report.py preview-cards --input <write-plan.json>
+```
+
+Se usuario nao confirmar, finalize sem escrever no Anki, sem registrar no `FLASHCARDS_INDEX.json` e sem marcar notas com tag `anki`.
+
+Modo direto opcional: se usuario pedir explicitamente `--create`, `--direct`, `--yes`, `--no-preview`, "criar diretamente", "crie direto", "sem preview", "sem previa" ou "sem confirmacao", pule apenas essa confirmacao de preview. Fluxo direto ainda valida modelo, filtra duplicados, respeita falhas do Anki MCP e registra apenas cards aceitos.
+
+Se houver mais de 40 cards candidatos, modo padrao mostra preview completo e pede confirmacao antes de qualquer escrita.
+
+## Validacao De Modelo Anki
+
+Antes de chamar `mcp_anki-mcp_addNotes`/`mcp_anki-mcp_addNote`, valide modelo:
+
+```bash
+uv run python ${extensionPath}/scripts/mednotes/anki_model_validator.py validate --models-json <models.json>
+```
+
+JSON de entrada representa resultado de `modelNames` + `modelFieldNames`:
+
+```json
+{
+  "Medicina": ["Frente", "Verso", "Verso Extra", "Obsidian"],
+  "Medicina Cloze": ["Texto", "Verso Extra", "Obsidian"]
+}
+```
+
+Para validar os dois modelos juntos, use `validate-set`:
+
+```bash
+uv run python ${extensionPath}/scripts/mednotes/anki_model_validator.py validate-set --models-json <models.json>
+```
+
+Se algum modelo faltar campos obrigatorios, pare e rode `flashcards/install_models.py ensure` p/ instalar/atualizar.
+
+## Sincronizacao Das Twenty Rules
+
+Para auditar copia local contra pacote Anki MCP instalado:
+
+```bash
+uv run python ${extensionPath}/scripts/mednotes/sync_anki_twenty_rules.py check
+```
+
+Use `--source <content.md>` p/ apontar explicitamente para o prompt upstream. Use `write` apenas p/ substituir copia local pela upstream.
+
+## Relatorio Final
+
+Quando fluxo tiver dados estruturados de fontes, duplicados, cards aceitos, validacao de modelo e erros do Anki MCP, gere resposta final com:
+
+```bash
+uv run python ${extensionPath}/scripts/mednotes/flashcard_report.py final --input <run-result.json>
+```
+
+Relatorio deve separar: notas processadas, cards criados, cards pulados por duplicidade, notas puladas, erros de modelo/campos e erros do Anki MCP.

package/.opencode/mednotes/docs/knowledge-architect.md

@@ -0,0 +1,208 @@
+---
+name: med-knowledge-architect
+description: Guardião do Padrão Ouro da Wiki Medicina. Define estrutura de Mini-Aula, taxonomia por especialidades e zonas gerenciadas pelo linker.
+---
+
+# Med Knowledge Architect (A Mente)
+
+Autoridade de estrutura, estilo e taxonomia da `Wiki_Medicina`. Grafo,
+WikiLinks, aliases e `Notas Relacionadas` pertencem a `semantic-linker.md`.
+
+## 🏆 O Padrão Ouro: Estrutura de Mini-Aula
+
+Toda nota deve funcionar como aula de alto rendimento para residência. Cubra,
+quando aplicável: título médico preciso; epidemiologia; etiologia/fisiopatologia;
+apresentação clínica; diferenciais; diagnóstico com padrão-ouro vs exame inicial;
+manejo/tratamento; fechamento; notas relacionadas.
+
+Fechamento obrigatório: `## 🏁 Fechamento`, com `### Resumo`,
+`### Key Points` e `### Frase de Prova`.
+
+## 🧱 Formato Wiki
+
+- Primeiro heading após YAML: `# Título Médico Preciso`.
+- YAML mínimo e canônico: somente `aliases`, tags operacionais (`anki`,
+  `revisar`, `indice`/`índice`), `chats[]` e metadados `images_*`
+  preservados/adicionados por workflows. Não inclua `title`, `tipo`, `status`,
+  `fonte`, taxonomia, categoria ou tag clínica. Omita YAML se tudo estiver
+  vazio.
+- Quando YAML existir, listas devem ser sempre multiline (`aliases:\n  - ...`,
+  `tags:\n  - ...`); nunca use listas inline como `aliases: [...]` ou
+  `tags: [...]`. Nunca adicione `tags: [medicina]` ou tag clínica genérica.
+- `indice`/`índice` marca notas operacionais que devem ser ignoradas por grafo,
+  linker, bootstrap/reset e auditorias de estilo; não use essa tag em nota
+  clínica comum.
+- Nota operacional Dataview ou de índice não segue o modelo de nota médica:
+  preserve frontmatter, queries, code blocks e layout operacional; não adicione
+  seções clínicas, `## 🏁 Fechamento`, `## 🔗 Notas Relacionadas`, provenance ou
+  reescrita didática.
+- Não invente tags; não use `cardio`, `gastro`, especialidades ou categorias em
+  `tags`. Taxonomia clínica é caminho de pasta.
+- Após o título, escreva definição de 2-4 linhas: o que é e por que cai.
+- A nota deve responder: quando pensar? como confirmar? o que fazer? qual
+  pegadinha?
+- Todo `##` começa com um emoji semântico: `🎯`, `🧠`, `🔎`, `🩺`, `⚖️`, `⚠️`,
+  `🏁`, `🔗`, `🧬`.
+- Separe parágrafos, listas, tabelas, callouts e headings por linha em branco.
+- Callouts Obsidian ficam isolados: `> [!tip]`, `> [!warning]`, `> [!danger]`,
+  `> [!info]`.
+- Tabelas Markdown devem ter colunas consistentes. Em tabela, escape pipe de
+  alias: `[[Cineangiocoronariografia (Cateterismo)\|CATE]]`.
+- Sempre inclua `## 🔗 Notas Relacionadas` como heading estrutural. Não
+  preencha bullets manualmente; `/mednotes:link` reescreve o bloco gerenciado.
+- Proveniência de chat é contrato do parent: `chats[]` é o campo consultável e
+  `## 🧬 Fontes Consolidadas` é a seção visível final. Não use rodapé legado.
+
+```markdown
+---
+chats:
+  - id: <fonte_id>
+---
+...
+## 🧬 Fontes Consolidadas
+- [Título do chat](https://gemini.google.com/app/<fonte_id>)
+```
+
+Não troque por URL local, deeplink Obsidian, `Fonte`, `Original` ou backlink
+para o índice. Não escreva bullets de `## 🔗 Notas Relacionadas`; essa seção é
+gerenciada pelo linker.
+
+## Diagramas Mermaid E Equacoes
+
+Use Mermaid ou equacoes quando uma secao clinica tiver fluxo, classificacao,
+cadeia causal, algoritmo decisorio ou calculo que fique mais claro como
+representacao visual ou matematica. O bloco deve ficar dentro da secao clinica
+correspondente, logo depois do texto que o justifica.
+
+Nao crie secao generica de "Mapa Mental", "Diagramas" ou "Formulas". Nao use
+visual decorativo. Nao invente relacoes, etapas, numeros, limiares ou formulas
+que nao estejam sustentados pelo material-fonte.
+
+Se a secao ja estiver clara em texto linear, nao force Mermaid nem equacao.
+
+## Artefatos Do Gemini
+
+Se o parent fornecer `artifact_manifests` com schema
+`gemini-md-export.artifact-html-manifest.v1`, cada HTML é insumo obrigatório do
+grupo de notas do raw chat. Não inline HTML no Markdown. A nota que carregar o
+artefato deve incluir iframe, link auditável e comentário:
+
+```markdown
+<iframe src="file:///CAMINHO/ARTEFATO.html" width="100%" height="820" loading="lazy"></iframe>
+[abrir artefato HTML](file:///CAMINHO/ARTEFATO.html)
+<!-- gemini-artifact
+chat_id: <chatId>
+manifest: <artifact-manifest-path>
+file: <artifact-html-path>
+sha256: <hash>
+-->
+```
+
+Se o parent fornecer `gemini-md-export.artifact-image-manifest.v1`, cada imagem
+gerada/exportada pelo Gemini também é insumo obrigatório. A nota que carregar a
+imagem deve incluir embed Markdown, legenda didática e o mesmo comentário de
+proveniência:
+
+```markdown
+![Legenda didática](file:///CAMINHO/IMAGEM.png)
+
+*Figura: Legenda didática.* *Fonte: Gemini Web — https://gemini.google.com/app/<chatId>*
+
+<!-- gemini-artifact
+kind: image
+chat_id: <chatId>
+manifest: <artifact-manifest-path>
+file: <artifact-image-path>
+sha256: <hash>
+-->
+```
+
+Se algum HTML ou imagem obrigatória faltar, bloqueie o raw chat e nomeie o
+arquivo. Não contorne autenticação, cookies, sandbox, CORS ou permissões.
+
+## 🇧🇷 Brasil vs Internacional
+
+- Se UpToDate/diretriz internacional divergir de diretriz brasileira, mostre
+  ambas e destaque a conduta esperada em prova brasileira.
+- Inclua pegadinhas de ENARE/SES-DF/SUS-SP quando conhecidas.
+
+## 🎨 Callouts
+
+- `> [!tip] Pulo do Gato`: mnemônicos.
+- `> [!warning] Pegadinha de Banca`: confusões frequentes.
+- `> [!danger] Red Flag`: sinais de alarme.
+- `> [!info] Diretriz Brasileira`: divergência nacional relevante.
+
+## 📂 Taxonomia
+
+A taxonomia operacional é somente caminho de pastas de categoria sob
+`Wiki_Medicina`; o `title` vira o arquivo `.md`. Use
+`1. Clínica Médica/Cardiologia/Arritmias` + título `Fibrilação Atrial`; nunca
+inclua o título como pasta final.
+
+Fonte de verdade: `scripts/mednotes/wiki_tree.py --max-depth 4 --audit`
+(`--format text` para leitura humana). Alternativas operacionais:
+`taxonomy-canonical`, `taxonomy-tree`, `taxonomy-audit`. Política canônica:
+`bundle/docs/taxonomy-policy.md`, derivada de `wiki/taxonomy/policy.py`.
+
+Áreas fixas: `1. Clínica Médica`, `2. Cirurgia`,
+`3. Ginecologia e Obstetrícia`, `4. Pediatria`, `5. Medicina Preventiva`.
+Não invente sexta área, categoria canônica, grafia, singular/plural, pasta
+intermediária ou variação de acento/underscore. Reuse a árvore real exatamente.
+Nova pasta fora do prefixo canônico só pode ser **uma folha única** sob pai
+coerente e autorizada pelo dry-run em `taxonomy_new_dirs`.
+Nova leaf pode aparecer em dry-run, mas publish real só pode criar a pasta se o
+recibo do dry-run para o mesmo manifest autorizar exatamente aqueles
+`taxonomy_new_dirs`.
+Em `3. Ginecologia e Obstetrícia`, a grande área é combinada, mas as categorias
+filhas são separadas: use `Ginecologia` ou `Obstetrícia`; nunca crie ou mire
+`3. Ginecologia e Obstetrícia/Ginecologia e Obstetrícia`.
+
+Mínimo: `Grande Área/Categoria/Título.md`. Grupos abaixo da categoria são
+opcionais quando já existem ou quando o dry-run autoriza. Não crie
+`1. Clínica Médica/Clínica Médica/Semiologia`.
+
+Movimentos preexistentes são CLI, não manuais:
+`taxonomy-migrate --dry-run --plan-output <plano.json>`;
+`taxonomy-migrate --apply --plan <plano.json> --receipt <recibo.json>`;
+`taxonomy-migrate --rollback --receipt <recibo.json>`.
+
+Distribuição canônica: `1. Clínica Médica` inclui Cardiologia, Dermatologia,
+Endocrinologia, Gastroenterologia, Geriatria, Hematologia, Imunologia,
+Infectologia, Medicina Interna, Nefrologia, Neurologia, Nutrologia, Oncologia,
+Pneumologia, Reumatologia, Semiologia, Psiquiatria; `2. Cirurgia` inclui
+Cirurgia Geral, Clínica Cirúrgica, Oftalmologia, Urologia, Trauma,
+Anestesiologia; `3. Ginecologia e Obstetrícia` inclui Ginecologia e Obstetrícia
+como categorias filhas separadas;
+`4. Pediatria` inclui Pediatria, Neonatologia, Puericultura, Infecto Pediátrica;
+`5. Medicina Preventiva` inclui Medicina Preventiva, SUS, Epidemiologia, Ética
+Médica, Saúde do Trabalho.
+
+## 🔗 Grafo E Triagem
+
+- **Identidade:** `1 meaning canônico = 1 nota Wiki`. Quando mais de um chat
+  cobre o mesmo meaning, escreva uma nota canônica com múltiplos `chats[]` e
+  deltas em `## 🧬 Fontes Consolidadas`.
+- **Grafo/linker:** A nota médica deve reservar a seção `## 🔗 Notas Relacionadas`,
+  mas WikiLinks, aliases, body linker e Related Notes são do
+  `/mednotes:link`. Não invente links nem bullets manuais para cumprir quota.
+- **Triagem:** Toda nota vem de raw chat triado com `titulo_triagem` e
+  `note_plan` descritivo/exaustivo.
+- **Chats longos:** A triagem inventaria todos os temas duráveis. Cada tema vira
+  `planned_meaning` ou recebe motivo tipado para não virar nota. Architect segue
+  esse plano, não subconjunto.
+- **Fidelidade ao chat-fonte:** Em notas derivadas de `Chats_Raw`, o architect
+  deve preservar toda informação médica relevante do raw chat nas notas
+  planejadas. O Padrão Ouro organiza/complementa, mas não pode substituir,
+  omitir ou diluir critérios, achados, condutas, exceções, comparações,
+  exemplos, perguntas/respostas, mecanismos, exames, contraindicações ou
+  detalhes de prova.
+- **Deduplicação:** `planned_meaning` não pode duplicar outro item por normalização
+  de acento/caixa, nota existente ou raw chat do lote. Duplicata de alvo novo
+  vira um único `canonical_merge`; duplicata de nota existente chama o architect
+  para reescrever o alvo canônico e o parent aplica com `apply-canonical-merge`.
+  Ambiguidade bloqueia com decisão humana; nunca escreva nota paralela.
+- **Índice Dataview:** o índice do vault é operacional e mantido pelo plugin
+  Dataview/Obsidian, não pelo architect. Se receber uma nota marcada
+  `indice`/`índice`, preserve-a como operacional e não tente convertê-la em
+  mini-aula médica.

package/.opencode/mednotes/docs/merge-policy.md

@@ -0,0 +1,110 @@
+# Merge Policy
+
+Política canônica de merge para notas da `Wiki_Medicina`. Pareada com
+`agent-role-contracts.md`, `triage-policy.md` e `semantic-linker.md`.
+
+Regra-âncora:
+
+> 1 meaning canônico = 1 nota Wiki.
+
+## Onde Cada Camada Decide
+
+- **Identidade na triagem** vive como `meaning_claim` na ação
+  `planned_meaning` do `triage-note-plan.v2`. O triager declara meaning a
+  partir do raw chat; ele não consulta a Wiki nem o vocabulary DB.
+- **Identidade no DB** vive como `primary_meaning` na curadoria do
+  `med-link-graph-curator`. Curator lê notas publicadas e consolida
+  meaning/aliases/surfaces no vocabulary DB. Pode propor `NoteMergeCandidate`,
+  nunca aplicar merge.
+- **Identidade no plano de execução** vive como `target_policy` nos work
+  items do planner (`new_note`, `canonical_rewrite`, `note_merge_candidate`
+  ou `blocked`). O planner cruza `meaning_claim` contra Wiki e DB.
+
+## Único Merge Permitido: `note_merge`
+
+A única API de merge entre notas publicadas é
+`bundle/scripts/mednotes/wiki/note_merge.py`. Caminho canônico:
+
+```text
+identidade semântica explícita / curator / decisão humana
+  → NoteMergeCandidate
+  → NoteMergePlan
+  → med-knowledge-architect rewrite (com preservation_report)
+  → apply-note-merge --dry-run
+  → apply-note-merge
+  → link trigger + reference repair
+```
+
+Hash de fontes prova estabilidade de input, não preservação clínica. O
+`preservation_report` do architect é o gate de preservação.
+
+## Proibições
+
+- **Sem merge title-driven**: detectores `duplicate_stem`, `duplicate_title`
+  ou similar não podem alimentar merge automático. Título parecido vira
+  diagnóstico de higiene no `fix-wiki`, nunca candidato.
+- **Sem `duplicate_merge` API**: `bundle/scripts/mednotes/wiki/duplicate_merge.py`
+  e `fix-wiki --phase duplicate-merge` estão deprecados; o caminho novo é
+  `note-merge`.
+- **Sem merge no architect**: architect rewrites a nota canônica quando
+  recebe `target_policy=canonical_rewrite` ou um work item de
+  `note_merge_candidate`, mas nunca decide identidade nem escolhe winner.
+- **Sem merge no triager**: triager não declara que duas unidades do mesmo
+  raw são o mesmo meaning de notas existentes; ele só descreve unidades
+  daquele raw.
+- **Sem merge silencioso**: quando há ambiguidade real, o planner emite
+  `human_decision_packet`; nada de chute por similaridade textual.
+
+## Como `meaning_claim` Resolve
+
+Para cada `planned_meaning` do triager, o planner faz uma lookup contra
+`vocabulary DB` (camada de identidade canônica) e contra a Wiki publicada.
+Saídas determinísticas:
+
+- **Match direto** (DB tem `primary_meaning` equivalente e Wiki tem nota
+  canônica): `target_policy = canonical_rewrite` apontando a nota existente.
+- **Match com divergência** (DB indica meaning igual a uma nota, mas outra
+  nota publicada também aparenta cobrir): `target_policy = note_merge_candidate`
+  com referência ao candidato emitido pelo curator ou bloqueio para decisão
+  humana.
+- **Sem match** (DB não tem meaning equivalente): `target_policy = new_note`
+  com path resolvido a partir de taxonomia + `staged_title`.
+- **Ambiguidade real** (claim conflita com mais de um canonical ou DB não
+  consegue cravar): `target_policy = blocked` com
+  `human_decision_packet`.
+
+Nenhuma dessas decisões usa título ou stem como chave primária. A chave é o
+`primary_meaning` no DB e o `meaning_claim` no plano.
+
+## Provenance Final
+
+Toda nota canônica com chats conhecidos termina com
+`## 🧬 Fontes Consolidadas` aplicada por `wiki.provenance`. O rodapé legado
+`Chat Original` é deprecado e removido pelo backfill interno de
+`/mednotes:fix-wiki`.
+
+## Aplicabilidade Universal
+
+- `/mednotes:process-chats` cria nota nova ou rewrite canônico usando
+  `meaning_claim` da triagem, provenance via `wiki.provenance`, sem
+  `duplicate_merge`. A resolução de `meaning_claim` pelo planner
+  determinístico é a direção canônica (implementação em plano separado).
+- `/mednotes:fix-wiki` normaliza o acervo antigo (backfill de `chats[]`,
+  remoção do rodapé legado, sincronização de `Fontes Consolidadas`) e gera
+  diagnósticos de higiene, mas **não** aplica merge title-driven.
+- `/mednotes:link` opera somente em grafo/linker; nunca faz merge.
+- Note merge real só roda via fase própria, alimentada por
+  `NoteMergeCandidate` semanticamente justificado.
+
+## Migração De Candidatos Legados
+
+Candidatos `duplicate_stem` ainda persistidos no vocabulary DB precisam ser
+revisados antes do detector ser removido. O caminho é um job de curator que:
+
+- relê cada candidato;
+- propõe `NoteMergeCandidate` quando há identidade semântica real (com
+  evidência citável do DB ou da nota);
+- descarta com motivo redigido quando o candidato era ruído title-driven.
+
+Sem essa migração, candidatos legados ficam órfãos e a remoção do detector
+perde trabalho.