Imported from daanmt/MedHub (.agents/skills/source-command-engenharia-cli/SKILL.md). Install upstream with npx skills add daanmt/MedHub --skill source-command-engenharia-cli. Copyright stays with the author.

source-command-engenharia-cli

Use this skill when the user asks to run the migrated source command engenharia-cli.

Command Template

Skill: CLIs de Engenharia

Portador canônico da assinatura (AGENTE.md §7.2: "cada CLI em tools/ tem assinatura canônica em UMA skill") dos CLIs que não têm casa numa skill de estudo — sensores do harness, manutenção do ipub.db, curadoria em lote e instrumentos de auditoria. O que este arquivo não é: orquestração. Sequência de passos é do workflow (.agents/workflows/); aqui está o que cada flag faz.

Por que ele existe (D5, s177). A regra §7.2 nunca teve instrumento. Medido em 11/09/2026, antes deste arquivo: 65 de 168 flags (≈39%) não apareciam em skill nenhuma e 17 CLIs não eram citados por skill alguma — entre eles recurate_cards (o reescritor in-place que grava no baralho) e normalize_taxonomia (declaradamente destrutivo). O sensor que passou a medir isso é tools/cli_signature_check.py, documentado aqui embaixo como qualquer outro.

🔴 Fronteira dura de leitura: um CLI marcado [DESTRUTIVO] grava no ipub.db. Para qualquer um deles vale AGENTE.md §10.7 — tools/backup_db.py antes, dry-run é o default, e o COUNT esperado é declarado antes de --apply.

Sensores do harness (read-only, WARN-first)

Todos seguem a mesma convenção: detectam e reportam, nunca corrigem, nunca bloqueiam, e expõem run_checks() com a mesma assinatura para o auto_check consumir.

tools/cli_signature_check.py — assinatura canônica de CLI × skill (D5)

Flag órfã = declarada por add_argument no CLI e ausente de toda skill que cita aquele arquivo. Extração pela AST, não por regex sobre o texto — a 1ª versão leu a própria docstring e se acusou. Limites declarados na docstring do módulo (parser dinâmico escapa; mede presença, não semântica; flag genérica pode colar em skill vizinha e inflar a cobertura).

tools/consistencia_check.py — consistência entre registros (G5 · G10 · G14)

Três registros que envelheciam em silêncio porque nada perguntava se ainda diziam a verdade: tabela (a §7.4 do AGENTE.md é gerada e colada — cada CLI novo a deixa stale) · paths (tools/*.py inexistente citado num doc de raiz; o MEMORY_POINTERS só alcançava memory/) · status (achado **ABERTO** no AUDITORIA_MEDHUB.md com lápide de FEITO no §11). 🔴 Duas regras de precisão nasceram de medição: linha que afirma a ausência é lápide, não ponteiro morto; e PARCIAL não é contradição — é o meio-termo declarado.

O módulo também é a casa de duas derivações que o auto_check consome no lugar de listas digitadas: portadores_derivados() (F95) e termos_revogados_do_ledger() (o (ii') do F90, lido dos marcadores <!-- TERMO-REVOGADO: ... --> do §12 do inventário).

tools/doc_drift.py — drift doc-vs-código

tools/reachability_check.py — alcançabilidade (D4)

tools/card_self_sufficiency.py — card que não se sustenta sozinho

tools/ledger_self.py — ledger-of-self (memória dos WARNs do harness)

⚠️ O contador de recorrência mede quantas vezes o sensor rodou com o achado aberto, não tamanho de dívida. Para atomicidade, a cifra de dívida é tools/reforja.py --fila (ver estilo-flashcard.md) — os dois números divergem por construção e isso está declarado.

tools/learning_efficacy.py — eficácia de aprendizado por dimensão

tools/review_radar.py — radar de dormência por TEMA

Alimenta a seleção do tema dormente; o carimbo em review_log é de dormant_refresh.py (assinatura em revisar.md).

tools/fsrs_load.py — carga do calendário FSRS (read-only, exceto --blackout --apply)

Manutenção do ipub.db — todos [DESTRUTIVO], dry-run por default

tools/normalize_taxonomia.py — saneia taxonomia_cronograma (Fase 1 da curadoria)

Resolve o que a dedup não pega: encoding/acento, área inválida fora de core/areas.json, duplicata conceitual (mesmo tema, nomes diferentes), [bulk]/Geral vazios. Transação atômica, re-aponta FKs, recria UNIQUE(area,tema) no fim — duplicata restante causa rollback.

tools/cards_prune.py — poda de flashcards [DESTRUTIVO], o único caminho de EXCLUSÃO

Rito do --apply, nunca pulado: backup_db.py -> export das linhas das 4 tabelas para artifacts/backups/pruned_<ts>.json -> DELETE em UMA transação (fsrs_revlog -> reforja_marks -> fsrs_cards -> flashcards) -> COUNT-ASSERT pós (caiu exatamente N, nenhum id sobreviveu). Não existe flag para pular o backup. Não toca questoes_erros, taxonomia, review_log, nem stability/difficulty. Origem: PRD plano-ssot-e-cards-v2 P5 (s183) -- lote 1 = 125 aposentados sem histórico; os 67 com histórico ficam até triagem. Spec .vibeflow/specs/plano-ssot-e-cards-v2-part-5.md.

tools/dedup_taxonomia.py — colapsa (area,tema) duplicados exatos

MAX é o default porque taxonomia.questoes_realizadas não é o SSOT de volume (esse é sessoes_bulk) — somar inflaria um número que ninguém deveria ler como verdade.

tools/backfill_review_log.py — semeia review_log com a última revisão REAL

Nunca usa a data de hoje (falsificaria a curva): deriva de MAX(fsrs_cards.last_review) ou de taxonomia.ultima_revisao. Tema sem sinal real é pulado. Idempotente. Rodar depois da dedup, para não semear ids que seriam mesclados.

tools/index_resumos.py — (re)indexa resumos/ no ChromaDB

Motor único de RAG = app/engine/rag.py, gold-only (indexa .md, não PDF).

Curadoria em lote de flashcards

A régua de autoria e a fila de reforja vivem em estilo-flashcard.md; a orquestração da curadoria, em .agents/workflows/curar-cards.md. Aqui está só a assinatura.

tools/recurate_cards.py — o reescritor in-place CANÔNICO [DESTRUTIVO]

Preserva card_id e portanto o estado FSRS (fsrs_cards/fsrs_revlog intactos); incrementa card_version. ALL-OR-NOTHING: falha de qualquer gate em qualquer item e nada é aplicado — lote parcialmente aplicado deixa o baralho num estado que ninguém sabe descrever. Quatro gates: schema · encoding (§4.5) · formulação · atomicidade sobre o conteúdo PROPOSTO (o remédio é auditado pelo mesmo critério que diagnosticou a doença).

tools/insert_card_extra.py — card adicional sobre um questao_id EXISTENTE

Difere de insert_questao.py: não cria questão nova — herda questao_id/tema_id do original. Idempotente por (questao_id, frente_pergunta). É o CLI da atomização: quando reforjar um card gera um 2º conceito do mesmo erro.

tools/detect_clones.py — near-duplicates por TEMA (read-only)

Complementa o linter sintático, que é cego a clone. Compara frente_pergunta + verso_resposta entre cards ativos do mesmo tema. Não grava nada — a fusão é curadoria.

tools/audit_flashcard_quality.py — sinais sintáticos + cross-field (read-only)

⚰️ A heurística F7 (léxico de competidor) foi revogada em 11/09/2026 — medição em AUDITORIA_MEDHUB.md §F7. Não reintroduzir sem nova medição.

Plano do Dia e fechamento

tools/day_plan.py — o Plano do Dia (boot) e os blocos derivados

Assinatura canônica deste CLI. revisar.md e cronograma.md o invocam e apontam para cá; a lista completa de flags vive aqui para não existir em dois lugares (§7.2). O boot já roda day_plan.py pelo hook SessionStart — AGENTE.md §2 passo 4: não re-rodar sem flag.

🔴 O passo sugerido por --difficulty segue o contrato v1.3: DRENAR primeiro, ensino só na Revisão Direcionada de fechamento. ⚰️ Até 11/09/2026 a string dizia "PREPARAR ...; depois DRENAR" — sub-modo revogado na s170 que sobreviveu no código porque o gate CONTRATO_REVOGADO só varria markdown (F97). tools/day_plan.py e tools/dormant_refresh.py agora estão na lista de portadores do gate.

Posição no cronograma

tools/preparacao.py — posição SSOT da preparação (semana de conteúdo)

--set-semana e --show são mutuamente exclusivos e obrigatórios (um dos dois). A distinção que este CLI carrega: semana de conteúdo ≠ semana de calendário — o atraso entre as duas é a posição real, e o derivador do cronograma é tools/cronograma.py (assinatura em cronograma.md).

tools/plano.py -- o plano de estudo como DADO (plano_tarefas)

As três fontes, todas versionadas em core/cronograma/: grade_extensivo.json (735 tarefas / 52 semanas, part-1) · grade.json (Reta Final -- entram só as pendentes de S17-S28) · plano_custom.json (editável à mão). O status inicial vem de dashboard_snapshot.json, snapshot congelado do Drive (origem_conclusao=dashboard_2026-09-10) -- nunca se lê o Drive em runtime (cronograma-contract Cláusula 5b).

🔴 Semear nunca infere conclusão. Nome que não casa entre o PDF e o Dashboard nasce pendente, e o número de não-casados é impresso no dry-run. A semana_plano é decidida por duas funções puras testadas (ordenar_fase1, para as 7 semanas até a prova da UERJ em 01/11, e ordenar_fase2, para o extensivo S21-S48 a partir da semana 8) -- não por regra em JSON. Área fora de core/areas.json é recusada na porta (F89); rótulo que a fonte não tem como resolver (o Multi das tarefas de Radiologia) grava area=NULL com a nota dizendo qual rótulo era, que é dívida declarada e não chute.

Escrita só por app/utils/db.py (plano_upsert_tarefas, plano_set_status, plano_mover, plano_confirmar_area) -- o CLI é camada fina e não abre sqlite3 próprio; leitura por plano_listar, plano_obter e plano_pendencia_revisao. Idempotente por UNIQUE(fonte, ref_semana_fonte, tarefa_fonte): re-semear insere 0 e reescreve apenas CAMPOS_SEMEADOS -- status, data_conclusao, sessao_bulk_id e origem_conclusao são progresso e ficam fora do UPDATE. ⚠️ nota está em CAMPOS_SEMEADOS: o motivo de um --cortar é reescrito por um --semear --apply futuro (o status='cortada' sobrevive) -- dívida declarada, o motivo é explicação e não o dado de controle.

Exatamente UM modo por invocação (--semear | --listar | --concluir | --cortar | --mover | --reabrir | --revisar-area | --confirmar-area | --pendencia-revisao); dois modos ligados -> exit 2 nomeando os dois. Mutação de UMA linha grava direto: dry-run + --expect são o rito da operação em lote (--semear, --confirmar-area), AGENTE.md §10.7.

🔴 A revisão por área existe porque o status semeado é aproximado: o usuário confessou marcar tarefa no lugar de outra no Dashboard. O ciclo é --revisar-area (o agente lê os blocos com ele) -> --confirmar-area --dry-run -> --apply --expect N, com N = a área inteira, porque a conferência carimba origem_conclusao=usuario até em quem não muda de status -- a conferência é a evidência, e é isso que faz o --pendencia-revisao chegar a zero. Id fora da área (ou inexistente) derruba o lote inteiro, sem gravar nada. --confirmar-area é retro-confirmação: não inventa sessao_bulk_id nem apaga o de um --concluir anterior.

🔴 Semântica de origem_conclusao alargada na part-3: até a part-2 ela só era escrita em linha feita; agora responde "quem afirmou este status" em qualquer status (usuario vs. dashboard_2026-09-10). É trilha de auditoria, não status -- uma linha pode continuar feita e só trocar de origem, que é como "zero aproximadas" acontece sem reescrever histórico.

Specs .vibeflow/specs/plano-ssot-e-cards-v2-part-2.md (semeadura) e -part-3.md (progresso).