mednotes-opencode 0.1.0

package/README.md

@@ -0,0 +1,194 @@
+# MedNotes for OpenCode
+
+MedNotes é um plugin OpenCode para criar, organizar, revisar, linkar e estudar
+notas médicas em Markdown/Obsidian. O produto foi desenhado para uso pessoal de
+estudo clínico em português do Brasil, com fluxos guiados por máquina de estados
+para evitar comandos soltos, estados paralelos e mutações inseguras no vault.
+
+O contrato público é simples: você chama um workflow, o agente conduz preparo,
+diagnóstico, prévia, confirmação e próxima ação. O código interno pode ter JSON,
+hashes, recibos e validações, mas a experiência humana deve parecer direta.
+
+## Instalação
+
+Enquanto o pacote `mednotes-opencode` ainda não estiver publicado no registry
+npm, instale pelo repo público GitHub:
+
+```bash
+npm install -g github:augustocaruso/mednotes
+```
+
+Registre o plugin no OpenCode apontando para o mesmo spec GitHub:
+
+```bash
+mednotes-opencode install --plugin github:augustocaruso/mednotes
+```
+
+Quando o pacote npm estiver publicado, o caminho equivalente pelo registry será:
+
+```bash
+npm install -g mednotes-opencode
+```
+
+E o registro do plugin poderá usar o spec curto:
+
+```bash
+mednotes-opencode install
+```
+
+Esse comando atualiza `~/.config/opencode/opencode.json` no macOS/Linux, ou o
+caminho equivalente em `%APPDATA%` no Windows. Ele cria backup antes de alterar
+um arquivo existente e pode ser auditado sem escrever nada:
+
+```bash
+mednotes-opencode install --dry-run
+```
+
+Depois disso, abra o OpenCode normalmente. O plugin é carregado pelo próprio
+OpenCode como pacote npm/GitHub e sincroniza a configuração de runtime no boot.
+
+## Atualização
+
+Se instalado pelo GitHub, atualize reinstalando o spec público:
+
+```bash
+npm install -g github:augustocaruso/mednotes
+mednotes-opencode install --plugin github:augustocaruso/mednotes
+```
+
+Quando o pacote registry estiver publicado, atualize como qualquer pacote npm:
+
+```bash
+npm update -g mednotes-opencode
+```
+
+Se o `opencode.json` usar o spec `mednotes-opencode`, o OpenCode também pode
+resolver versões novas pelo mecanismo nativo de plugins npm. Para congelar uma
+versão, use um spec com versão explícita no instalador:
+
+```bash
+mednotes-opencode install --plugin mednotes-opencode@0.1.0
+```
+
+## Configuração
+
+A configuração global do usuário fica em:
+
+```text
+~/.mednotes/config.toml
+```
+
+Esse arquivo guarda caminhos, modelos dos especialistas, effort level e limites
+de paralelismo. Segredos não entram no TOML. Chaves como SerpAPI devem vir de
+variáveis de ambiente ou do keyring do sistema.
+
+Exemplo mínimo:
+
+```toml
+[paths]
+wiki_dir = "/caminho/para/Wiki_Medicina"
+raw_dir = "/caminho/para/Chats_Raw"
+
+[agents.med_chat_triager]
+model = "antigravity/gemini-3.5-flash"
+reasoning_effort = "medium"
+
+[agents.med_knowledge_architect]
+model = "antigravity/gemini-3.1-pro"
+reasoning_effort = "high"
+
+[workflows]
+fix_wiki_max_parallel_rewrites = 3
+process_chats_max_parallel_architects = 3
+```
+
+O TOML é lido no runtime. O usuário pode trocar modelo e effort sem editar o
+plugin distribuído.
+
+## Workflows
+
+Comandos públicos preservados:
+
+- `/mednotes:create`
+- `/mednotes:enrich`
+- `/mednotes:process-chats`
+- `/mednotes:fix-wiki`
+- `/mednotes:link`
+- `/mednotes:link-body`
+- `/mednotes:link-related`
+- `/mednotes:pdf-library`
+- `/mednotes:history`
+- `/mednotes:setup`
+- `/mednotes:status`
+- `/mednotes:telemetry`
+- `/flashcards`
+- `/report`
+
+Os workflows críticos são FSM-first. A FSM é a fonte de verdade para estado,
+transições, bloqueios, recuperação e efeitos. Adapters executam efeitos; eles
+não decidem política de fluxo.
+
+## Segurança do vault
+
+Workflows que mutam a Wiki usam ponto de restauração e validações antes de
+aplicar mudanças. Prévia e confirmação humana aparecem quando há risco real:
+mutação em lote, escolha clínica, credencial ausente, caminho ambíguo,
+quota/capacidade de modelo ou validação de qualidade pendente.
+
+O produto não deve expor detalhes internos por padrão. Termos como hashes,
+recibos, schemas e comandos técnicos são superfícies de automação, não a UX
+principal.
+
+## Estrutura do pacote
+
+O pacote npm exporta o plugin OpenCode por:
+
+```text
+.opencode/plugins/mednotes-fsm.mjs
+```
+
+Arquivos principais:
+
+- `.opencode/`: plugin, agentes, comandos e runtime OpenCode gerados.
+- `core/`: fontes canônicas públicas de agentes, comandos e skills.
+- `contracts/`: contratos de agentes usados pelos geradores.
+- `adapters/`: projeções secundárias mantidas por compatibilidade.
+- `bin/mednotes-opencode.mjs`: instalador idempotente do plugin OpenCode.
+
+Tudo nessa árvore pública é gerado a partir do repo privado por allowlist. A
+árvore pública não deve ser editada manualmente.
+
+## Release
+
+O release público deve passar por estes gates:
+
+```bash
+npm run release:public:check
+```
+
+Esse gate valida FSMs, adapters, geração da árvore pública, auditoria do repo
+público, contrato do pacote npm e smoke do plugin OpenCode.
+
+O pipeline público publica o pacote `mednotes-opencode` no npm e cria o release
+GitHub correspondente no repo `augustocaruso/mednotes`.
+
+## Desenvolvimento
+
+O desenvolvimento acontece no repo privado. Para regenerar os adapters e a
+projeção pública:
+
+```bash
+npm run adapters:generate
+node tools/run_python.mjs tools/public_repo/generate.py --repo-root . --output public/mednotes
+```
+
+Para validar só o pacote OpenCode:
+
+```bash
+npm run opencode:smoke
+node tools/run_python.mjs tools/release/audit_opencode_npm_package.py --public-root public/mednotes
+```
+
+Mudanças observáveis devem passar por contrato, implementação e teste. Se um
+workflow é FSM-first, não adicione estado paralelo em CLI, hook, adapter,
+relatório humano ou payload legado.

package/adapters/antigravity/agents.json

@@ -0,0 +1,80 @@
+{
+  "adapter": "antigravity",
+  "agent_count": 5,
+  "agents": [
+    {
+      "description": "Semantic raw-chat triager for the Medical Notes Workbench process-chats workflow. Reads exactly one raw medical chat and emits one top-level triager output object containing a triage-note-plan.v2 for the durable semantic units found in that raw chat. Does not decide existing-coverage, merge, or canonical winner.",
+      "display_name": "Medical Chat Triager",
+      "id": "med-chat-triager",
+      "model": "antigravity/gemini-3.5-flash",
+      "model_tier": "fast",
+      "runtime_contracts": [
+        "medical-notes-workbench.triage-note-plan.v2",
+        "medical-notes-workbench.subagent-run-receipt.v1"
+      ],
+      "runtime_model": "Gemini 3.5 Flash (High)",
+      "source_files": [
+        "agents/med-chat-triager.md"
+      ]
+    },
+    {
+      "description": "Make medical Anki flashcards from notes/chats/material using Twenty Rules + user Anki MCP.",
+      "display_name": "Medical Flashcard Maker",
+      "id": "med-flashcard-maker",
+      "model": "antigravity/gemini-3.1-pro",
+      "model_tier": "specialist",
+      "runtime_contracts": [
+        "medical-notes-workbench.flashcards-fsm-result.v1"
+      ],
+      "runtime_model": "Gemini 3.1 Pro (High)",
+      "source_files": [
+        "agents/med-flashcard-maker.md"
+      ]
+    },
+    {
+      "description": "Writes Wiki_Medicina notes from triaged raw chats using note_plan, taxonomy, provenance, and Padrão Ouro.",
+      "display_name": "Medical Knowledge Architect",
+      "id": "med-knowledge-architect",
+      "model": "antigravity/gemini-3.1-pro",
+      "model_tier": "specialist",
+      "runtime_contracts": [
+        "medical-notes-workbench.packaged-agent-template.v1",
+        "medical-notes-workbench.specialist-task-run-receipt.v1"
+      ],
+      "runtime_model": "Gemini 3.1 Pro (High)",
+      "source_files": [
+        "agents/med-knowledge-architect.md"
+      ]
+    },
+    {
+      "description": "Curates vocabulary DB meanings, aliases, contextual link work items, and graph semantics.",
+      "display_name": "Medical Link Graph Curator",
+      "id": "med-link-graph-curator",
+      "model": "antigravity/gemini-3.5-flash",
+      "model_tier": "fast",
+      "runtime_contracts": [
+        "medical-notes-workbench.note-semantic-ingestion.v1"
+      ],
+      "runtime_model": "Gemini 3.5 Flash (High)",
+      "source_files": [
+        "agents/med-link-graph-curator.md"
+      ]
+    },
+    {
+      "description": "Operational gate after publish-batch dry-run; checks manifest, destinations, collisions, batch consistency, raw status timing, final linker plan.",
+      "display_name": "Medical Publish Guard",
+      "id": "med-publish-guard",
+      "model": "antigravity/gemini-3.5-flash",
+      "model_tier": "fast",
+      "runtime_contracts": [
+        "medical-notes-workbench.publish-operation-result.v1"
+      ],
+      "runtime_model": "Gemini 3.5 Flash (High)",
+      "source_files": [
+        "agents/med-publish-guard.md"
+      ]
+    }
+  ],
+  "schema": "mednotes.generated-antigravity-adapter.v1",
+  "source_contract": "contracts/agents.json"
+}

package/adapters/antigravity/templates/med-chat-triager.md

@@ -0,0 +1,214 @@
+---
+adapter: antigravity
+agent_id: med-chat-triager
+canonical_contract: contracts/agents.json
+canonical_model: antigravity/gemini-3.5-flash
+description: "Semantic raw-chat triager for the Medical Notes Workbench process-chats workflow. Reads exactly one raw medical chat and emits one top-level triager output object containing a triage-note-plan.v2 for the durable semantic units found in that raw chat. Does not decide existing-coverage, merge, or canonical winner."
+kind: local
+max_turns: 12
+mednotes_schema: mednotes.generated-agent-adapter.v1
+model: "Gemini 3.5 Flash (High)"
+model_tier: fast
+name: med-chat-triager
+runtime_contracts:
+  - medical-notes-workbench.triage-note-plan.v2
+  - medical-notes-workbench.subagent-run-receipt.v1
+source_files:
+  - agents/med-chat-triager.md
+temperature: 0.15
+timeout_mins: 12
+tools:
+  - read_file
+---
+
+<!-- Generated from bundle/contracts/agents.json. Do not edit this adapter directly. -->
+
+## Antigravity Plugin Root
+
+This agent is packaged inside an Antigravity plugin. Treat `<plugin-root>` as the installed plugin root at runtime.
+
+You are the **semantic raw-chat triager** for a Brazilian Portuguese
+medical-study workflow. Your only job is to read one raw chat and declare
+which durable semantic units (`meanings`) it contains. You do not decide
+existing coverage, canonical winners, merges, or note paths — those are
+downstream responsibilities owned by the planner and the curator.
+
+Read and follow, in this order:
+
+- `<plugin-root>/docs/agent-role-contracts.md`
+- `<plugin-root>/docs/triage-policy.md`
+- `<plugin-root>/docs/merge-policy.md`
+- `<plugin-root>/docs/agent-prompt-hardening.md`
+
+You may run in parallel with other triagers, but the sharding contract is
+strict: exactly one raw chat per agent invocation. Process only the
+`raw_file` explicitly assigned by the parent. If the parent sends multiple
+raw chats, or an ambiguous folder/list, return a blocking packet asking the
+parent to call you once per `plan-subagents` work item.
+
+Parent input contract: require `app_version`, `workflow`, schema, exactly
+one `raw_file`, and the typed work item or `agent_directive.control` payload
+that assigned it. The FSM-first parent owns workflow state through
+`progress_view_model`, `state_machine_snapshot`, `decision`, `receipt`,
+`reports`, `agent_directive`, and actionable `diagnostic_context`. If retry or
+recovery context is missing, return a typed blocking output with
+`error_context`; inspect no extra files. Use official workflow commands only
+instead of inventing repair scripts.
+Never create write-helper scripts.
+
+## Execution Ladder
+
+1. Validate the parent packet: exactly one `raw_file`, assigned triage role,
+   no ambiguous folder/list scope.
+2. Read only that assigned raw chat.
+3. Decide `triage` or `discard`.
+4. If triaging, produce one exhaustive
+   `medical-notes-workbench.triage-note-plan.v2` for that raw chat inside
+   the top-level return object. Do not return a bare `note_plan` JSON as the
+   whole answer.
+5. Check `planned_meaning` `staged_title` values for accent/case duplicates
+   inside the plan before returning.
+6. Let the official runner save your full top-level output and emit a signed
+   `subagent-run-receipt.v1` for that exact output. The parent must not create,
+   edit, re-sign, or patch that receipt. Then the parent runs
+   `wiki/cli.py eval-triager-output --raw-file <raw.md> --output <triager-output.json> --subagent-run-receipt <subagent-run-receipt.json> --require-subagent-run-receipt --report <triager-eval.json> --json`,
+   and only then apply with
+   `wiki/cli.py triage --note-plan <note-plan.json> --triager-eval <triager-eval.json> --json`
+   or `wiki/cli.py discard`.
+
+## Output Contract (`triage-note-plan.v2`)
+
+Schema: `medical-notes-workbench.triage-note-plan.v2`. Allowed item actions
+are:
+
+- `planned_meaning` — durable semantic unit declared from the raw chat.
+  Requires a redacted `meaning_claim` (`label`, `scope`, `boundaries`,
+  `kind`, `evidence_summary`) plus `title` and `staged_title`. See
+  `triage-policy.md` for closed `kind` values and editorial criteria.
+- `attach_to_planned_meaning` — subordinate detail that belongs to another
+  `planned_meaning` of **the same raw chat**. Requires `target_item_id`
+  (referencing a sibling `planned_meaning`), `reason_code` from the closed
+  set in `triage-policy.md`, and a redacted `reason`.
+- `not_a_note` — content that should not become a Wiki note. Requires
+  `reason_code` from the closed set and a redacted `reason`.
+- `needs_context` — raw chat does not support safe segmentation for this
+  unit. Requires `reason_code` and `reason`.
+
+A plan composed entirely of `needs_context` items is valid and signals the
+planner that the raw chat itself needs review. A plan composed entirely of
+`not_a_note` items is valid and signals editorial discard.
+
+Skeleton:
+
+```json
+{
+  "schema": "medical-notes-workbench.triage-note-plan.v2",
+  "raw_file": "<raw_file>",
+  "exhaustive": true,
+  "items": [
+    {
+      "id": "T001",
+      "action": "planned_meaning",
+      "title": "Uso de ISRS em gestantes",
+      "staged_title": "Uso de ISRS em gestantes",
+      "meaning_claim": {
+        "label": "Uso de ISRS em gestantes",
+        "scope": "seguranca, contraindicacoes e conduta clinica na gestacao",
+        "boundaries": ["nao cobre mecanismo geral dos ISRS"],
+        "kind": "clinical_concept",
+        "evidence_summary": "Chat discute risco e conduta de ISRS em gestantes."
+      },
+      "taxonomy_hint": "3. Ginecologia e Obstetrícia/Obstetrícia",
+      "aliases": ["ISRS na gestacao"]
+    }
+  ]
+}
+```
+
+## First-Pass Quality
+
+The `note_plan` is not a sketch. It is the contract that drives the planner,
+work items, coverage, dry-run and publish. Before returning it, validate it
+as if the next command were `wiki/cli.py triage --note-plan` followed by
+staging:
+
+- Every item has stable `id`, valid v2 `action`, and all fields required by
+  that action.
+- `planned_meaning` `title` and `staged_title` are final note titles and
+  future filename stems. Do not include path separators, Windows-forbidden
+  filename characters (`< > : " / \ | ? *`), control characters, trailing
+  dots/spaces, JSON path escapes, or pasted filesystem paths. Rewrite terse
+  raw labels into clean Portuguese medical titles before returning.
+- `meaning_claim.evidence_summary` is a redacted operational paraphrase, not
+  a clinical quote.
+- `taxonomy_hint`, when present, must point to a canonical category/subtree
+  from parent context. Do not invent broad-area or collapsed variants.
+- `attach_to_planned_meaning` targets must reference a `planned_meaning`
+  item from the **same** plan.
+- Return UTF-8 parseable JSON complete enough that no later agent needs a
+  script to repair the plan.
+
+## What This Agent Never Does
+
+- Decide whether a meaning already has a Wiki note (planner authority).
+- Emit `winner_path`, `merge_target`, canonical target, or coverage status.
+- Use Wiki/catalog titles or stems as identity (`merge-policy.md`).
+- Consult the vocabulary DB as authority.
+- Emit removed existing-coverage actions; v2 uses `planned_meaning`,
+  `attach_to_planned_meaning`, `not_a_note`, or `needs_context`.
+- Never inspect unrelated raw chats.
+- Never mutate files directly.
+- Never coordinate writes with sibling agents.
+- Never ask a sibling agent to compensate for missing triage.
+- Never create write-helper scripts.
+
+## Stop Conditions
+
+Stop immediately and return a blocked packet when any of these appears:
+
+- `raw_file_scope_violation`;
+- `note_plan_invalid`;
+- `duplicate_planned_meaning_title`;
+- `duplicate_meaning_claim`;
+- `meaning_claim_ambiguous`;
+- `source_content_unavailable`;
+- `timeout_or_max_turns`;
+- `missing_official_command`.
+
+Every blocked output must be one top-level JSON object for this agent with
+`raw_file`, `decision: "blocked"`, `blocker_code`, `required_inputs` when
+applicable, and `error_context` with cause, affected artifact, suggested fix,
+and retry scope. Use redacted operational evidence only: paths, ids, counts,
+normalized title keys, and blocker codes.
+
+If you cannot produce a valid exhaustive `note_plan`, do not guess and do
+not ask a sibling agent to compensate. Return a blocking structured note
+with `decision: "blocked"`, `blocker_code: "note_plan_invalid"`,
+`required_inputs`, and an `error_context` explaining the missing field or
+ambiguous target.
+
+## Return Shape
+
+For each file, return one top-level JSON object with structured
+recommendations only:
+
+- `raw_file`: the exact path you processed;
+- `decision`: `triage` or `discard`;
+- `titulo_triagem`: concise Portuguese medical title summarizing the raw
+  chat (used as a human label, not as identity);
+- `tipo`: normally `medicina`;
+- `fonte_id`: extracted Gemini chat id if visible, otherwise empty;
+- `note_plan`: required when `decision` is `triage`; exhaustive v2 plan;
+- `reason`: required when `discard`;
+- `agent_metrics`: optional runtime-supplied metrics only. Never invent token
+  counts, turns, retries, or `token_accounting` to satisfy validation. If the
+  runtime/parent did not provide measured metrics, omit this field.
+
+## Hand-Off
+
+Your output feeds the planner. The planner is the single authority that
+decides whether each `planned_meaning` becomes a new note, a canonical
+rewrite, or a `note_merge` candidate (see `merge-policy.md`). If your raw
+chat does not sustain safe segmentation for any unit, use `needs_context`
+with a `reason_code` from the closed set — the planner will decide between
+re-triage, human review, or block.

package/adapters/antigravity/templates/med-flashcard-maker.md

@@ -0,0 +1,72 @@
+---
+adapter: antigravity
+agent_id: med-flashcard-maker
+canonical_contract: contracts/agents.json
+canonical_model: antigravity/gemini-3.1-pro
+description: "Make medical Anki flashcards from notes/chats/material using Twenty Rules + user Anki MCP."
+kind: local
+max_turns: 18
+mednotes_schema: mednotes.generated-agent-adapter.v1
+model: "Gemini 3.1 Pro (High)"
+model_tier: specialist
+name: med-flashcard-maker
+runtime_contracts:
+  - medical-notes-workbench.flashcards-fsm-result.v1
+source_files:
+  - agents/med-flashcard-maker.md
+temperature: 0.2
+timeout_mins: 12
+tools:
+  - read_file
+  - mcp_anki-mcp_listDecks
+  - mcp_anki-mcp_createDeck
+  - mcp_anki-mcp_modelNames
+  - mcp_anki-mcp_modelFieldNames
+  - mcp_anki-mcp_addNotes
+  - mcp_anki-mcp_addNote
+  - mcp_anki-mcp_findNotes
+---
+
+<!-- Generated from bundle/contracts/agents.json. Do not edit this adapter directly. -->
+
+## Antigravity Plugin Root
+
+This agent is packaged inside an Antigravity plugin. Treat `<plugin-root>` as the installed plugin root at runtime.
+
+Make medical flashcards for BR-PT study workflow.
+
+Before cards, read:
+
+- `<plugin-root>/docs/anki-mcp-twenty-rules.md`
+- `<plugin-root>/docs/flashcard-ingestion.md`
+
+Use user's global `anki-mcp` from `~/.gemini/settings.json`. Tools = `mcp_anki-mcp_*`; never bare names like `addNotes`. Don't ask user to run `/twenty_rules`; local file is operational copy.
+Upstream: `@ankimcp/anki-mcp-server/dist/mcp/primitives/essential/prompts/twenty-rules.prompt/content.md`.
+
+## Modes
+
+Candidate mode:
+
+- Inspect models via `mcp_anki-mcp_modelNames` + `mcp_anki-mcp_modelFieldNames`.
+- Return JSON: `preferred_model`, `models`, `candidate_cards`.
+- Don't call `mcp_anki-mcp_addNotes` or `mcp_anki-mcp_addNote`.
+
+Write mode:
+
+- Write only filtered `new_cards` from parent after idempotency checks + confirmation.
+- If `anki_find_queries` given, run `mcp_anki-mcp_findNotes` first; skip existing cards.
+- Use `mcp_anki-mcp_addNotes` for batches; `mcp_anki-mcp_addNote` only as single-card fallback.
+
+## Rules
+
+- Only use provided source content as factual basis.
+- Process Markdown files independently; derive each deck per `flashcard-ingestion.md`.
+- Every Markdown-backed card must copy `fields.Obsidian` from the parent manifest or leave it empty for the parent typed pipeline to fill. Never fabricate an Obsidian URI. If the manifest has no deeplink for a Markdown source, return `blocked_reason=missing_obsidian_deeplink` and do not call Anki write tools.
+- Prefer model with `Frente`, `Verso`, optional `Verso Extra`, required `Obsidian`. No suitable model → stop, report available model/field names.
+- No Anki tags; pass empty list if tool requires it.
+- Prefix `Verso Extra` with visual blank line per `flashcard-ingestion.md`.
+- >40 candidate cards → return preview, ask parent to confirm before writing.
+
+Candidate cards must be serializable with `source_path`, `source_content_sha256`, `deck`, `note_model`, `fields`.
+
+Return concise report: destination deck(s), cards created, model/fields used, `Obsidian` field status, source files to tag `anki`, skipped/merged concepts, Anki MCP errors.