Colliers × Costal — Interno

operacao-scripts

Leitura de 4 min

Scripts Operacionais

operacao scripts

Scripts Python para manutenção e validação do vault.

Scripts disponíveis

ScriptCategoriaO que faz
vault-lint.pylintVerifica convenção de nomes em todo o vault (MEMORY-CONTRACT §4.1)
validate-tasks.pylintIntegridade referencial task→pessoa→time→sprint
fix-mermaid.pyfix automatizávelCorrige subgraph X["N. ..."] → ["N — ..."] (apenas dentro de blocos mermaid)
fix-pipe-escapes.pyfix automatizávelRemove | em wikilinks que NÃO estão dentro de tabelas markdown
export-tasks-dashboard.pygeradorRegenera TASKS.md a partir das notas em 00-projeto/tasks/ (com backup automático)
normalize-task-owners.pynormalizadorNormaliza slugs curtos (pedro → pedro-villa) em frontmatter de tasks
normalize-task-sprints.pynormalizadorNormaliza valores legados de sprint: para slugs canônicos
migrate-tasks-to-notes.pymigrador (uso único)Migrou TASKS.md monolítico para 1-task-1-nota
migrate-pessoas-to-directory.pymigrador (uso único)Migrou perfis de 06-directory/pessoas para 00-projeto/directory/pessoas
refactor-directory-paths.pyrefator (uso único)Ajustou wikilinks 06-directory/ → 00-projeto/directory/
fix-alias-slashes.py · fix-tasks-origens.py · onda3-migration*.pyuso únicoRefatorações específicas concluídas

vault-lint.py

Verifica:

  • Ausência de acentos em nomes de arquivo
  • Ausência de espaços
  • Minúsculas
  • Formato YYYY-MM-DD_descricao-curta ou kebab-case (com sufixos semânticos opcionais via _)

Exceções permitidas: top-level em maiúscula (HOME.md, HOME-board.md, HOME-cliente.md, README.md, TASKS.md, MEETINGS.md, DEFINICOES.md, STYLE-GUIDE.md, MEMORY-CONTRACT.md, AXIOS-HANDOFF.md, SCREENER-HANDOFF.md), folder notes (<nome-da-pasta>.md, ex: 02-costal.md, canonico.md) e templates (_template.md, _templates/*.md).

Extensões verificadas: .md, .pdf, .docx, .xmind, .png, .jpg, .xlsx, .pptx.

Uso

# Lint completo
python3 99-operacao/scripts/vault-lint.py
 
# Escopo reduzido
python3 99-operacao/scripts/vault-lint.py --path 01-colliers
 
# Sugestões de rename (dry-run)
python3 99-operacao/scripts/vault-lint.py --fix-dry

Retorna exit code 0 se limpo, 1 se há violações.

Quando rodar

  • Antes de commit material no vault
  • Semanalmente (checklist de governança do Axios)
  • Após ingestão de lote novo de PDFs/documentos

fix-mermaid.py

Corrige subgraph X["N. Texto"] → subgraph X["N — Texto"] apenas dentro de blocos ```mermaid — o parser do Mermaid em Obsidian/Quartz interpreta N. como abertura de lista markdown e quebra com Unsupported markdown: list.

Detecção restrita ao bloco Mermaid evita falsos-positivos em documentação que cita o padrão como exemplo de “como NÃO fazer” (ex: STYLE-GUIDE).

Uso

python3 99-operacao/scripts/fix-mermaid.py             # vault inteiro
python3 99-operacao/scripts/fix-mermaid.py --dry-run   # mostra correções sem escrever
python3 99-operacao/scripts/fix-mermaid.py --path 02-costal

Quando rodar

  • Após gerar/editar diagramas Mermaid em qualquer doc
  • Em CI/pré-commit se houver Quartz publicação
  • --dry-run semanal junto com vault-lint

fix-pipe-escapes.py

Normaliza | em wikilinks por contexto, nas duas direções.

ContextoRegraO que o script faz
Wikilink em tabela (linha começa com |, não-separator)[[X|alias]] (pipe escapado)Adiciona | se faltar
Wikilink em prosa / lista / header / blockquote[[X|alias]] (pipe simples)Remove | se houver

A heurística de detecção de tabela: linha cujo strip() começa com | e que não é a linha separator.

Uso

python3 99-operacao/scripts/fix-pipe-escapes.py             # vault inteiro
python3 99-operacao/scripts/fix-pipe-escapes.py --dry-run
python3 99-operacao/scripts/fix-pipe-escapes.py --path HOME.md

O output marca cada amostra com PRS (prosa) ou TBL (tabela) para facilitar revisão.

Quando rodar

  • Sempre antes de publicação no Quartz
  • Em CI/pré-commit
  • Após gerar tasks via migrate-tasks-to-notes.py

export-tasks-dashboard.py

Regenera TASKS.md na raiz do vault a partir das notas individuais em 00-projeto/tasks/T-XXX.md. Gera dashboard read-only com 9 seções (resumo executivo, críticas, atrasadas, em progresso, bloqueadas, carga por owner, todas ativas, concluídas, próximo ID).

Uso

python3 99-operacao/scripts/export-tasks-dashboard.py

Backup automático

Antes de sobrescrever, salva versão anterior em 99-operacao/_archive/tasks-dashboard/TASKS.YYYY-MM-DD_HHMMSS.md (rolling window de 30).

Visualização kanban (sem script)

Para uma visualização tipo kanban das tasks, abrir _bases/tasks-pipeline.base no Obsidian. A Base tem 19 views configuradas, cada uma equivalente a uma “coluna” ou “lente” do kanban:

  • Por status: 🟡 Em progresso · 🔴 Bloqueadas · ⚪ Abertas · ⏸️ Pendentes · ✅ Concluídas
  • Por owner: 👤 Pedro · Rafael · Antônio · Gabriel
  • Por frente: 🏢 Colliers · 🏗️ Costal · 🧠 Anouk Interno · 🤝 Anouk Cliente
  • Por prazo: 📅 Hoje · Esta semana · ⚠️ Críticas · 📊 Todas ativas
  • Por sprint: 🚀 Sprint atual

Vantagens vs kanban file separado:

  • Zero setup — Bases já está habilitado, qualquer pessoa abre e vê
  • Sempre atualizado — lê direto das notas T-XXX, sem regenerar
  • Read-only por design — Bases não permite edição via interface
  • Filtros poderosos — clicar entre tabs já filtra

Para alterar uma task: clicar no ID da nota na tabela → abre a nota individual em 00-projeto/tasks/T-XXX.md → editar campos no frontmatter → salvar. A view atualiza automaticamente.

Fluxo recomendado pré-publicação

Antes de publicar wiki ou commitar mudanças materiais:

python3 99-operacao/scripts/validate-tasks.py     # integridade referencial tasks
python3 99-operacao/scripts/vault-lint.py         # convenção de nomes
python3 99-operacao/scripts/fix-mermaid.py --dry-run
python3 99-operacao/scripts/fix-pipe-escapes.py --dry-run

Aplicar correções (sem dry-run) só após inspecionar o relatório do dry-run.

Para regenerar dashboard de tasks:

python3 99-operacao/scripts/export-tasks-dashboard.py    # TASKS.md

Backup automático em 99-operacao/_archive/.

Ver também

Visão de gráfico

Backlinks