From cb90e4d858cacfb93b9682c4d9ef634a5b11f2f7 Mon Sep 17 00:00:00 2001 From: Luiz Silva Date: Wed, 14 Oct 2026 17:12:10 -0300 Subject: [PATCH] implementado graphify.sh --- .gitignore | 5 + DOCUMENTACAO/templates/plano.md.template | 6 + TOOLS | 17 ++- TOOLS.md | 17 ++- global/skills/plano.executar/SKILL.md | 9 +- global/skills/plano/SKILL.md | 20 ++- global/workflows/plano.md | 13 +- scripts/graphify.sh | 156 +++++++++++++++++++++++ skills/plano.executar/SKILL.md | 9 +- skills/plano/SKILL.md | 20 ++- validar-setup.sh | 15 ++- 11 files changed, 261 insertions(+), 26 deletions(-) create mode 100755 scripts/graphify.sh diff --git a/.gitignore b/.gitignore index acf74b6..51cf8eb 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,8 @@ node_modules/ .vscode/ .idea/ *.swp + +# Graphify Knowledge Graph +.graphify/ +.engram/ +graphify-out/ diff --git a/DOCUMENTACAO/templates/plano.md.template b/DOCUMENTACAO/templates/plano.md.template index b41e04d..e16391e 100644 --- a/DOCUMENTACAO/templates/plano.md.template +++ b/DOCUMENTACAO/templates/plano.md.template @@ -53,6 +53,12 @@ executor: null - `caminho/do/arquivo1.ts` — - `caminho/do/arquivo2.vue` — +### Raio de Impacto & Dependências (Graphify) + +- **Nós / Símbolos Centrais:** `` +- **Arquivos Dependentes Impactados:** `` +- **Cadeias Críticas / Lacunas de Teste:** `` + --- ## 3. Critérios de Aceite & Validação (Definition of Done) diff --git a/TOOLS b/TOOLS index eaea253..9fb7ccf 100644 --- a/TOOLS +++ b/TOOLS @@ -115,6 +115,17 @@ Este documento lista ferramentas de linha de comando (CLI) e utilitários que ot - **Por que ajuda as IAs e Operadores:** Previne o inchaço (*bloat*) do Git da Wiki desacoplando binários pesados (PDFs, imagens em alta resolução, vídeos, capturas de tela e anexos), gerando links e snippets Markdown prontos para inclusão imediata na documentação. - **Uso:** `sh .agent/scripts/upload-paiol-wiki.sh [modulo-override]` +### graphify.sh (`.agent/scripts/graphify.sh`) +- **Descrição:** Utilitário canônico de Grafo de Conhecimento (*Knowledge Graph*) do código-fonte baseado em `@sentropic/graphify`. +- **Por que ajuda as IAs:** Permite que o comando `/plano` e os agentes localizem símbolos, mapeiem dependências entre pacotes e calculem o raio de impacto em cascata (*Blast Radius*) em segundos sem varreduras cegas. Instala automaticamente o binário via Bun (`bun i -g @sentropic/graphify`) caso não exista na máquina, atualiza o `.gitignore` (`.graphify/`, `.engram/`, `graphify-out/`) e gera o grafo sob demanda (`ensure`). +- **Uso:** + - `bash .agent/scripts/graphify.sh update` (reconstrói/atualiza o grafo AST) + - `bash .agent/scripts/graphify.sh ensure` (garante instalação, `.gitignore` e grafo existente) + - `bash .agent/scripts/graphify.sh query "" [budget]` (busca nós e arquivos no grafo) + - `bash .agent/scripts/graphify.sh explain ""` (detalha conexões e imports) + - `bash .agent/scripts/graphify.sh impact [arq2...]` (calcula raio de impacto e lacunas de testes via `review-delta`) + - `bash .agent/scripts/graphify.sh summary` (exibe principais hubs e comunidades do projeto) + --- ## 8. Instalação Rápida (Copia e Cola) @@ -131,8 +142,8 @@ sudo apt-get install -y ripgrep fd-find jq shellcheck bat tree eza httpie gh # 2. Instalar ferramentas em Node npm install -g @ast-grep/cli @biomejs/biome -# 3. Instalar automação de navegador para IA (visível com --headed) -bun i -g agent-browser && agent-browser install +# 3. Instalar automação de navegador e Grafo de Conhecimento para IA via Bun +bun i -g agent-browser @sentropic/graphify && agent-browser install # 4. Instalar yq via snap sudo snap install yq @@ -144,5 +155,5 @@ sudo snap install yq # Instalar utilitários essenciais brew install ripgrep fd ast-grep jq yq shellcheck bat tree eza httpie gh npm install -g @biomejs/biome -bun i -g agent-browser && agent-browser install +bun i -g agent-browser @sentropic/graphify && agent-browser install ``` diff --git a/TOOLS.md b/TOOLS.md index eaea253..9fb7ccf 100644 --- a/TOOLS.md +++ b/TOOLS.md @@ -115,6 +115,17 @@ Este documento lista ferramentas de linha de comando (CLI) e utilitários que ot - **Por que ajuda as IAs e Operadores:** Previne o inchaço (*bloat*) do Git da Wiki desacoplando binários pesados (PDFs, imagens em alta resolução, vídeos, capturas de tela e anexos), gerando links e snippets Markdown prontos para inclusão imediata na documentação. - **Uso:** `sh .agent/scripts/upload-paiol-wiki.sh [modulo-override]` +### graphify.sh (`.agent/scripts/graphify.sh`) +- **Descrição:** Utilitário canônico de Grafo de Conhecimento (*Knowledge Graph*) do código-fonte baseado em `@sentropic/graphify`. +- **Por que ajuda as IAs:** Permite que o comando `/plano` e os agentes localizem símbolos, mapeiem dependências entre pacotes e calculem o raio de impacto em cascata (*Blast Radius*) em segundos sem varreduras cegas. Instala automaticamente o binário via Bun (`bun i -g @sentropic/graphify`) caso não exista na máquina, atualiza o `.gitignore` (`.graphify/`, `.engram/`, `graphify-out/`) e gera o grafo sob demanda (`ensure`). +- **Uso:** + - `bash .agent/scripts/graphify.sh update` (reconstrói/atualiza o grafo AST) + - `bash .agent/scripts/graphify.sh ensure` (garante instalação, `.gitignore` e grafo existente) + - `bash .agent/scripts/graphify.sh query "" [budget]` (busca nós e arquivos no grafo) + - `bash .agent/scripts/graphify.sh explain ""` (detalha conexões e imports) + - `bash .agent/scripts/graphify.sh impact [arq2...]` (calcula raio de impacto e lacunas de testes via `review-delta`) + - `bash .agent/scripts/graphify.sh summary` (exibe principais hubs e comunidades do projeto) + --- ## 8. Instalação Rápida (Copia e Cola) @@ -131,8 +142,8 @@ sudo apt-get install -y ripgrep fd-find jq shellcheck bat tree eza httpie gh # 2. Instalar ferramentas em Node npm install -g @ast-grep/cli @biomejs/biome -# 3. Instalar automação de navegador para IA (visível com --headed) -bun i -g agent-browser && agent-browser install +# 3. Instalar automação de navegador e Grafo de Conhecimento para IA via Bun +bun i -g agent-browser @sentropic/graphify && agent-browser install # 4. Instalar yq via snap sudo snap install yq @@ -144,5 +155,5 @@ sudo snap install yq # Instalar utilitários essenciais brew install ripgrep fd ast-grep jq yq shellcheck bat tree eza httpie gh npm install -g @biomejs/biome -bun i -g agent-browser && agent-browser install +bun i -g agent-browser @sentropic/graphify && agent-browser install ``` diff --git a/global/skills/plano.executar/SKILL.md b/global/skills/plano.executar/SKILL.md index c61f101..8f68b17 100644 --- a/global/skills/plano.executar/SKILL.md +++ b/global/skills/plano.executar/SKILL.md @@ -123,6 +123,7 @@ Em implementações integradas, o Orquestrador segue a ordem canônica de handof ### 1. Leitura e Decomposição - Lê o plano integralmente com `view_file`. - Mapeia os critérios de aceite (Definition of Done) na Seção 3 e especificações na Seção 4. +- Caso novos arquivos precisem ser inspecionados além dos previstos no plano, consulta o Grafo de Conhecimento via `bash .agent/scripts/graphify.sh explain ""` ou `bash .agent/scripts/graphify.sh impact `. - Orquestrador define os especialistas necessários. ### 2. Implementação Especializada @@ -151,14 +152,16 @@ Ao atingir 100% de conformidade com todos os critérios do plano: - Seção 6 (*Histórico de Execução*): arquivos modificados, resumo da solução e evidências de validação. 2. **Mover o Plano:** - Salvar em `./PLANOS/executado/.md` e remover de `./PLANOS/pendente/.md` (preservando o nome original do arquivo). -3. **Memória do Projeto (Pilar 6 - @documentacao):** +3. **Atualizar Grafo de Conhecimento (Graphify):** + - Executar `bash .agent/scripts/graphify.sh update` para atualizar o grafo de código com os novos símbolos, arquivos e relações implementados (garantindo automaticamente a instalação via Bun se ausente e as regras no `.gitignore`). +4. **Memória do Projeto (Pilar 6 - @documentacao):** - Criar `memorias-ia/sessao-AAAA-MM-DD-.md`. - Indexar no `memorias-ia/historico-acoes.md`. -4. **Staging e Commit Semântico:** +5. **Staging e Commit Semântico:** - Executar `git add ` e `git status`. - Inspecionar a branch atual com `git branch --show-current`: se estiver em `master` (ou `main`), criar e alternar para uma nova branch semântica (`git checkout -b /`) — **NUNCA comitar diretamente em `master`** (ver `rules/proibido-commit-ia.md`). - Executar o `git commit` semântico na branch de trabalho (`git commit -m "(): "`). -5. **Notificação no Sistema Operacional (Linux & macOS):** +6. **Notificação no Sistema Operacional (Linux & macOS):** - Disparar notificação sonora e visual no SO via script `.agent/notificar.sh`: `sh .agent/notificar.sh "Plano Concluído" "" sucesso` - O utilitário detecta automaticamente se o host é Linux (KDE `kdialog`, `notify-send`, `gdbus`, PipeWire/PulseAudio) ou macOS (`osascript` banner nativo + `afplay` áudio Glass + terminal bell `\a`), emitindo o alerta em background no ambiente do operador mesmo quando rodando via CLI. diff --git a/global/skills/plano/SKILL.md b/global/skills/plano/SKILL.md index 144ff3a..7d4d21b 100644 --- a/global/skills/plano/SKILL.md +++ b/global/skills/plano/SKILL.md @@ -43,10 +43,22 @@ Quando invocado com uma instrução (ex.: `/plano corrigir validação do númer - Caminho alvo: `./PLANOS/pendente/AAAA-MM-DD-HH-mm-.md`. - **Propósito da Nomenclatura:** A inclusão de hora (`HH`) e minuto (`mm`) no prefixo temporal viabiliza a ordenação lexicográfica determinística da fila (FIFO — First In, First Out), permitindo que `/plano.executar todos` processe os planos estritamente na ordem em que foram criados. -### 2. Diagnóstico Técnico Pré-Implementação (Sem alterar código) +### 2. Diagnóstico Técnico Pré-Implementação com Graphify (Sem alterar código) - **NÃO altere arquivos de código de produção nesta etapa.** -- Mapeie os pacotes afetados (`*-comuns`, `*-back`, `*-front`, `*-migracao`). -- Inspecione rapidamente arquivos relevantes com `view_file` ou `grep_search` para identificar a causa raiz, props, schemas Zod, rotas ou componentes envolvidos. +- **Consultar o Grafo de Conhecimento (`graphify.sh`):** + - O utilitário `.agent/scripts/graphify.sh` verifica e instala automaticamente o `@sentropic/graphify` via Bun caso não esteja instalado na máquina, atualiza de forma idempotente o `.gitignore` do projeto (`.graphify/`, `.engram/`, `graphify-out/`) e inicializa o grafo sob demanda (`ensure`) caso ainda não exista: + ```bash + # 1. Localizar nós, rotas, tabelas ou componentes relacionados à demanda + bash .agent/scripts/graphify.sh query "" + bash .agent/scripts/graphify.sh explain "" + ``` +- Inspecione rapidamente os arquivos candidatos com `view_file` ou `grep_search` para identificar a causa raiz, props, schemas Zod, rotas ou componentes envolvidos. +- **Mapear Raio de Impacto em Cascata (*Blast Radius*):** + - Com os arquivos candidatos identificados, execute a análise de impacto no grafo: + ```bash + bash .agent/scripts/graphify.sh impact + ``` + - Utilize a saída (`Impacted files`, `High-risk dependency chains`, `Likely test gaps`) para determinar com precisão todos os pacotes em `modulos-impactados` (`*-comuns`, `*-back`, `*-front`, `*-migracao`) e mapear efeitos colaterais entre módulos. - Identifique o comportamento atual vs comportamento esperado. ### 3. Redigir e Persistir o Arquivo de Plano @@ -71,7 +83,7 @@ Quando invocado com uma instrução (ex.: `/plano corrigir validação do númer --- ``` - **1. Objetivo & Contexto:** Descrição concisa da demanda e impacto de negócio. - - **2. Diagnóstico Técnico & Evidências:** Comportamento observado vs esperado, repro steps e arquivos mapeados com links `[arquivo](file://...)`. + - **2. Diagnóstico Técnico & Evidências:** Comportamento observado vs esperado, repro steps, arquivos mapeados com links `[arquivo](file://...)` e subseção **Raio de Impacto & Dependências (Graphify)** extraída via `bash .agent/scripts/graphify.sh impact`. - **3. Critérios de Aceite & Validação (DoD):** Checklist com caixas `- [ ]` contendo condições verificáveis de sucesso. - **4. Especificação Técnica & Passos de Implementação:** Roteiro prático para o desenvolvedor (schemas, backend, frontend, código sugerido). - **5. Plano de Verificação & Testes:** Testes automatizados (`typecheck`, `biome`) e roteiro manual/E2E com `agent-browser --session _ --headed`. diff --git a/global/workflows/plano.md b/global/workflows/plano.md index a2faa1f..d0b3fae 100644 --- a/global/workflows/plano.md +++ b/global/workflows/plano.md @@ -52,9 +52,11 @@ Durante a navegação, testes manuais ou homologação de telas e rotas, o teste Quando o comando for executado: -1. **Interpretação e Diagnóstico Rápido:** +1. **Interpretação e Diagnóstico Rápido com Graphify:** - A IA extrai o núcleo da demanda (o que está quebrado ou precisa ser feito). + - Consulta o Grafo de Conhecimento via `bash .agent/scripts/graphify.sh query ""` e `explain ""` (o script instala automaticamente o `@sentropic/graphify` via Bun caso não exista na máquina, atualiza o `.gitignore` e gera o grafo sob demanda). - Investiga o código-fonte (sem alterá-lo) para identificar arquivos, componentes Vue, rotas Bun/Hono, schemas Zod ou tabelas impactadas. + - Executa `bash .agent/scripts/graphify.sh impact ` para calcular o raio de impacto em cascata (*Blast Radius*), cadeias críticas e lacunas de testes entre pacotes. - Identifica a causa raiz ou o ponto exato de intervenção. 2. **Formatação do Nome do Arquivo:** @@ -67,7 +69,7 @@ Quando o comando for executado: - Preenche: - Frontmatter com `id: AAAA-MM-DD-HH-mm-`, `data-criacao: "AAAA-MM-DD HH:mm"`, `status: pendente` e tags do domínio. - Objetivo & Contexto (visão funcional). - - Diagnóstico Técnico & Evidências (repro steps e arquivos mapeados). + - Diagnóstico Técnico & Evidências (repro steps, arquivos mapeados e **Raio de Impacto & Dependências via Graphify**). - Critérios de Aceite (Definition of Done). - Especificação Técnica passo a passo para orientar o desenvolvedor. - Plano de Verificação & Testes. @@ -126,12 +128,15 @@ Ao confirmar que a implementação está verde e validada: para: `PLANOS/executado/.md` -3. **Registro na Memória do Projeto (Pilar 6 - @documentacao):** +3. **Atualização do Grafo de Conhecimento (Graphify):** + - Executa `bash .agent/scripts/graphify.sh update` para sincronizar o grafo do projeto com as alterações recém-implementadas. + +4. **Registro na Memória do Projeto (Pilar 6 - @documentacao):** - Cria o registro de sessão em `memorias-ia/sessao-AAAA-MM-DD-.md`. - Indexa no `memorias-ia/historico-acoes.md`. - Executa `git add` nos arquivos alterados e realiza o `git commit` semântico (se a branch atual for `master`, cria e seleciona previamente uma nova branch de trabalho — nunca comita em `master`, conforme `rules/proibido-commit-ia.md`). -4. **Notificação no Sistema Operacional (Linux & macOS):** +5. **Notificação no Sistema Operacional (Linux & macOS):** - Dispara alerta sonoro e notificação visual de desktop via `.agent/notificar.sh`: `sh .agent/notificar.sh "Plano Concluído" "" sucesso` - Na conclusão de toda a fila serial de `/plano.executar todos`, emite a notificação consolidada de encerramento do lote para avisar o operador no CLI. diff --git a/scripts/graphify.sh b/scripts/graphify.sh new file mode 100755 index 0000000..ceb56a6 --- /dev/null +++ b/scripts/graphify.sh @@ -0,0 +1,156 @@ +#!/usr/bin/env bash +# ============================================================================== +# Utilitário Canônico do Graphify (.agent/scripts/graphify.sh) +# Gerencia instalação automática via Bun, atualização idempotente do .gitignore, +# geração sob demanda (ensure) e consultas ao Grafo de Conhecimento para /plano. +# ============================================================================== + +set -e + +export PATH="$HOME/.bun/bin:$PATH" +export ENGRAM_QUIET_DEPRECATION=1 + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" + +# Resolver diretório raiz do projeto hospedeiro +resolver_raiz_projeto() { + local super_dir + super_dir=$(git -C "$SCRIPT_DIR" rev-parse --show-superproject-working-tree 2>/dev/null || true) + if [ -n "$super_dir" ]; then + echo "$super_dir" + return + fi + + local candidato + candidato="$(cd "$SCRIPT_DIR/../.." && pwd)" + if [ -d "$candidato/.agent" ] || [ -f "$candidato/memorias-ia/modulo.yml" ]; then + echo "$candidato" + return + fi + + pwd +} + +SUPER_DIR="$(resolver_raiz_projeto)" + +# 1. Garantir entradas do Graphify no .gitignore do projeto hospedeiro +garantir_gitignore() { + local gitignore_file="$SUPER_DIR/.gitignore" + if [ ! -f "$gitignore_file" ]; then + touch "$gitignore_file" + fi + + local adicionou_cabecalho=0 + if grep -qE "^# Graphify Knowledge Graph" "$gitignore_file" 2>/dev/null; then + adicionou_cabecalho=1 + fi + + for entrada in ".graphify/" ".engram/" "graphify-out/"; do + if ! grep -qxF "$entrada" "$gitignore_file" 2>/dev/null; then + if [ "$adicionou_cabecalho" -eq 0 ]; then + printf "\n# Graphify Knowledge Graph\n" >> "$gitignore_file" + adicionou_cabecalho=1 + fi + printf "%s\n" "$entrada" >> "$gitignore_file" + fi + done +} + +# 2. Garantir que o Graphify esteja instalado na máquina (via Bun) +garantir_instalacao() { + local forcar="${1:-0}" + if [ "$forcar" = "1" ] || { ! command -v graphify >/dev/null 2>&1 && ! command -v engram >/dev/null 2>&1; }; then + if command -v bun >/dev/null 2>&1; then + echo "📦 Instalando/atualizando Graphify globalmente via Bun (@sentropic/graphify)..." >&2 + bun i -g @sentropic/graphify >&2 || true + fi + fi +} + +# 3. Executar o binário do Graphify com fallback para bunx / bun x +executar_graphify() { + if command -v graphify >/dev/null 2>&1; then + graphify "$@" + elif command -v engram >/dev/null 2>&1; then + engram "$@" + elif command -v bunx >/dev/null 2>&1; then + bunx @sentropic/graphify "$@" + elif command -v bun >/dev/null 2>&1; then + bun x @sentropic/graphify "$@" + else + echo "Erro: Graphify não encontrado no PATH e Bun (bun/bunx) não está disponível na máquina." >&2 + exit 1 + fi +} + +# 4. Garantir existência do grafo sob demanda (modo ensure) +garantir_grafo() { + garantir_gitignore + garantir_instalacao 0 + if [ ! -f "$SUPER_DIR/.engram/graph.json" ] && [ ! -f "$SUPER_DIR/.graphify/graph.json" ]; then + echo "📊 Grafo de conhecimento ainda não existe em $SUPER_DIR. Gerando automaticamente..." >&2 + (cd "$SUPER_DIR" && executar_graphify update . --no-description >&2) + fi +} + +SUBCOMANDO="${1:-update}" +if [ $# -gt 0 ]; then + shift +fi + +case "$SUBCOMANDO" in + install) + garantir_gitignore + garantir_instalacao 1 + echo "✅ Graphify instalado e .gitignore atualizado em $SUPER_DIR!" + ;; + gitignore) + garantir_gitignore + echo "✅ .gitignore verificado e atualizado em $SUPER_DIR!" + ;; + ensure) + garantir_grafo + ;; + update) + garantir_gitignore + garantir_instalacao 0 + echo "📊 Atualizando o grafo de conhecimento (Graphify) em $SUPER_DIR..." + (cd "$SUPER_DIR" && executar_graphify update . --no-description "$@") + echo "✅ Grafo atualizado com sucesso!" + ;; + query) + if [ $# -lt 1 ]; then + echo "Uso: sh .agent/scripts/graphify.sh query \"\" [budget]" >&2 + exit 1 + fi + TERMO="$1" + BUDGET="${2:-1500}" + garantir_grafo + (cd "$SUPER_DIR" && executar_graphify query "$TERMO" --budget "$BUDGET") + ;; + explain) + if [ $# -lt 1 ]; then + echo "Uso: sh .agent/scripts/graphify.sh explain \"\"" >&2 + exit 1 + fi + garantir_grafo + (cd "$SUPER_DIR" && executar_graphify explain "$@") + ;; + impact) + garantir_grafo + if [ $# -eq 0 ]; then + (cd "$SUPER_DIR" && executar_graphify review-delta --depth 2) + else + CSV_FILES=$(IFS=,; echo "$*") + (cd "$SUPER_DIR" && executar_graphify review-delta --files "$CSV_FILES" --depth 2) + fi + ;; + summary) + garantir_grafo + (cd "$SUPER_DIR" && executar_graphify summary --top-hubs 5 --top-communities 5 "$@") + ;; + *) + garantir_grafo + (cd "$SUPER_DIR" && executar_graphify "$SUBCOMANDO" "$@") + ;; +esac diff --git a/skills/plano.executar/SKILL.md b/skills/plano.executar/SKILL.md index c61f101..8f68b17 100644 --- a/skills/plano.executar/SKILL.md +++ b/skills/plano.executar/SKILL.md @@ -123,6 +123,7 @@ Em implementações integradas, o Orquestrador segue a ordem canônica de handof ### 1. Leitura e Decomposição - Lê o plano integralmente com `view_file`. - Mapeia os critérios de aceite (Definition of Done) na Seção 3 e especificações na Seção 4. +- Caso novos arquivos precisem ser inspecionados além dos previstos no plano, consulta o Grafo de Conhecimento via `bash .agent/scripts/graphify.sh explain ""` ou `bash .agent/scripts/graphify.sh impact `. - Orquestrador define os especialistas necessários. ### 2. Implementação Especializada @@ -151,14 +152,16 @@ Ao atingir 100% de conformidade com todos os critérios do plano: - Seção 6 (*Histórico de Execução*): arquivos modificados, resumo da solução e evidências de validação. 2. **Mover o Plano:** - Salvar em `./PLANOS/executado/.md` e remover de `./PLANOS/pendente/.md` (preservando o nome original do arquivo). -3. **Memória do Projeto (Pilar 6 - @documentacao):** +3. **Atualizar Grafo de Conhecimento (Graphify):** + - Executar `bash .agent/scripts/graphify.sh update` para atualizar o grafo de código com os novos símbolos, arquivos e relações implementados (garantindo automaticamente a instalação via Bun se ausente e as regras no `.gitignore`). +4. **Memória do Projeto (Pilar 6 - @documentacao):** - Criar `memorias-ia/sessao-AAAA-MM-DD-.md`. - Indexar no `memorias-ia/historico-acoes.md`. -4. **Staging e Commit Semântico:** +5. **Staging e Commit Semântico:** - Executar `git add ` e `git status`. - Inspecionar a branch atual com `git branch --show-current`: se estiver em `master` (ou `main`), criar e alternar para uma nova branch semântica (`git checkout -b /`) — **NUNCA comitar diretamente em `master`** (ver `rules/proibido-commit-ia.md`). - Executar o `git commit` semântico na branch de trabalho (`git commit -m "(): "`). -5. **Notificação no Sistema Operacional (Linux & macOS):** +6. **Notificação no Sistema Operacional (Linux & macOS):** - Disparar notificação sonora e visual no SO via script `.agent/notificar.sh`: `sh .agent/notificar.sh "Plano Concluído" "" sucesso` - O utilitário detecta automaticamente se o host é Linux (KDE `kdialog`, `notify-send`, `gdbus`, PipeWire/PulseAudio) ou macOS (`osascript` banner nativo + `afplay` áudio Glass + terminal bell `\a`), emitindo o alerta em background no ambiente do operador mesmo quando rodando via CLI. diff --git a/skills/plano/SKILL.md b/skills/plano/SKILL.md index 144ff3a..7d4d21b 100644 --- a/skills/plano/SKILL.md +++ b/skills/plano/SKILL.md @@ -43,10 +43,22 @@ Quando invocado com uma instrução (ex.: `/plano corrigir validação do númer - Caminho alvo: `./PLANOS/pendente/AAAA-MM-DD-HH-mm-.md`. - **Propósito da Nomenclatura:** A inclusão de hora (`HH`) e minuto (`mm`) no prefixo temporal viabiliza a ordenação lexicográfica determinística da fila (FIFO — First In, First Out), permitindo que `/plano.executar todos` processe os planos estritamente na ordem em que foram criados. -### 2. Diagnóstico Técnico Pré-Implementação (Sem alterar código) +### 2. Diagnóstico Técnico Pré-Implementação com Graphify (Sem alterar código) - **NÃO altere arquivos de código de produção nesta etapa.** -- Mapeie os pacotes afetados (`*-comuns`, `*-back`, `*-front`, `*-migracao`). -- Inspecione rapidamente arquivos relevantes com `view_file` ou `grep_search` para identificar a causa raiz, props, schemas Zod, rotas ou componentes envolvidos. +- **Consultar o Grafo de Conhecimento (`graphify.sh`):** + - O utilitário `.agent/scripts/graphify.sh` verifica e instala automaticamente o `@sentropic/graphify` via Bun caso não esteja instalado na máquina, atualiza de forma idempotente o `.gitignore` do projeto (`.graphify/`, `.engram/`, `graphify-out/`) e inicializa o grafo sob demanda (`ensure`) caso ainda não exista: + ```bash + # 1. Localizar nós, rotas, tabelas ou componentes relacionados à demanda + bash .agent/scripts/graphify.sh query "" + bash .agent/scripts/graphify.sh explain "" + ``` +- Inspecione rapidamente os arquivos candidatos com `view_file` ou `grep_search` para identificar a causa raiz, props, schemas Zod, rotas ou componentes envolvidos. +- **Mapear Raio de Impacto em Cascata (*Blast Radius*):** + - Com os arquivos candidatos identificados, execute a análise de impacto no grafo: + ```bash + bash .agent/scripts/graphify.sh impact + ``` + - Utilize a saída (`Impacted files`, `High-risk dependency chains`, `Likely test gaps`) para determinar com precisão todos os pacotes em `modulos-impactados` (`*-comuns`, `*-back`, `*-front`, `*-migracao`) e mapear efeitos colaterais entre módulos. - Identifique o comportamento atual vs comportamento esperado. ### 3. Redigir e Persistir o Arquivo de Plano @@ -71,7 +83,7 @@ Quando invocado com uma instrução (ex.: `/plano corrigir validação do númer --- ``` - **1. Objetivo & Contexto:** Descrição concisa da demanda e impacto de negócio. - - **2. Diagnóstico Técnico & Evidências:** Comportamento observado vs esperado, repro steps e arquivos mapeados com links `[arquivo](file://...)`. + - **2. Diagnóstico Técnico & Evidências:** Comportamento observado vs esperado, repro steps, arquivos mapeados com links `[arquivo](file://...)` e subseção **Raio de Impacto & Dependências (Graphify)** extraída via `bash .agent/scripts/graphify.sh impact`. - **3. Critérios de Aceite & Validação (DoD):** Checklist com caixas `- [ ]` contendo condições verificáveis de sucesso. - **4. Especificação Técnica & Passos de Implementação:** Roteiro prático para o desenvolvedor (schemas, backend, frontend, código sugerido). - **5. Plano de Verificação & Testes:** Testes automatizados (`typecheck`, `biome`) e roteiro manual/E2E com `agent-browser --session _ --headed`. diff --git a/validar-setup.sh b/validar-setup.sh index 57f81d6..e1172df 100644 --- a/validar-setup.sh +++ b/validar-setup.sh @@ -182,14 +182,25 @@ else echo -e " ${AZUL}ℹ${RESET} .agent-local/ ausente (usando 100% regras e skills globais)." fi -# 6. Validar Limite de Linhas (Governança de Código) -echo -e "\n${NEGRITO}[6/6] Governança de Código (verificar-linhas.sh)${RESET}" +# 6. Validar Limite de Linhas e Grafo de Conhecimento (Governança de Código) +echo -e "\n${NEGRITO}[6/6] Governança de Código & Graphify (verificar-linhas.sh / graphify.sh)${RESET}" if [ -f "$ROOT_DIR/.agent/verificar-linhas.sh" ]; then sh "$ROOT_DIR/.agent/verificar-linhas.sh" > /dev/null 2>&1 && \ echo -e " ${VERDE}✓${RESET} 100% dos arquivos dentro do limite de 250 linhas." || \ echo -e " ${AMARELO}⚠${RESET} Há arquivos excedendo 250 linhas (execute sh .agent/verificar-linhas.sh)." fi +if [ -f "$ROOT_DIR/.agent/scripts/graphify.sh" ]; then + bash "$ROOT_DIR/.agent/scripts/graphify.sh" gitignore > /dev/null 2>&1 || true + echo -e " ${VERDE}✓${RESET} .gitignore configurado para Graphify (.graphify/, .engram/, graphify-out/)." + export PATH="$HOME/.bun/bin:$PATH" + if command -v graphify >/dev/null 2>&1 || command -v engram >/dev/null 2>&1; then + echo -e " ${VERDE}✓${RESET} CLI Graphify instalado na máquina." + else + echo -e " ${AZUL}ℹ${RESET} CLI Graphify será instalado automaticamente via Bun no primeiro uso de graphify.sh." + fi +fi + # Resumo Final echo -e "\n${AZUL}${NEGRITO}======================================================${RESET}" if [ "$TOTAL_ERROS" -eq 0 ]; then