feat(protheus): memória do legado, confiança rotulada e gates em arquivo (2.16.0)

.claude-plugin/marketplace.json

@@ -30,7 +30,7 @@
       "name": "protheus",
       "source": "./protheus",
       "description": "Plugin para desenvolvimento TOTVS Protheus — ciclo completo: brainstorm → plan → implement (Agent Teams) → deploy TDS-CLI → qa E2E → verify, geradores MVC/REST/query, dicionário de dados, SmartView/TReports e Knowledge Base remota (155k+ registros).",
-      "version": "2.15.0",
+      "version": "2.16.0",
       "author": {
         "name": "DataAgile"
       },

CHANGELOG.md

@@ -4,6 +4,65 @@ Histórico das versões públicas do `dataagile-agent-kit`.
 
 ---
 
+## [2.8.0] — 2026-08-08
+
+### O ciclo Protheus passou a lembrar do legado do cliente (protheus 2.16.0)
+
+Cada demanda começava do zero: ninguém sabia quais customizações já existiam na área que ia
+ser mexida, e o que a entrega anterior estabeleceu morria no patch. A nova skill
+**`/protheus:arqueologia`** mapeia **a fatia** que a demanda toca — customizações, Pontos de
+Entrada, dicionário customizado e regras de negócio embutidas — e grava em `docs/legado/`,
+append-only, com escala de confiança. Fatia já mapeada não é remapeada: é **conferida**, e
+divergência entre o mapa e o fonte de hoje vira achado.
+
+Do outro lado do ciclo, o `/protheus:verify` ganhou o **writeback** (Passo 2.5): terminada a
+liberação, o que a entrega criou volta para o mapa e para a lista de regressão. O
+`/protheus:plan` ganhou o **Passo 3.5**, que mede o alcance real da mudança (`grep` nos
+callers, confrontado com a lista fechada de fontes) e escreve o que **não pode quebrar** antes
+de salvar o plano — item verificável vira cenário E2E nomeado; item sem forma de verificar é
+observação, não regressão. O `/protheus:verify` bloqueia se algum item ficar sem veredito.
+
+### Confiança rotulada: CONFIRMADO, INFERIDO, LACUNA
+
+O `/protheus:specialist` passou a exigir **rótulo e fonte em toda afirmação técnica**, com teto
+por proveniência: conhecimento destilado de código pode chegar a CONFIRMADO; documentação
+sozinha tem teto INFERIDO. Dicionário de dados é INFERIDO até conferir no SX3 do cliente.
+
+A escala atravessa o ciclo: o `/protheus:diagnose` rotula a causa raiz **antes** de propor
+correção e não corrige sobre LACUNA; o `/protheus:brainstorm` recomenda com rótulo e fonte em
+cada pergunta.
+
+### Brainstorm por rodadas, e estado de pipeline em arquivo
+
+O `/protheus:brainstorm` trocou "uma pergunta por mensagem" por **rodadas de fronteira**: monta
+a árvore de decisão, pergunta de uma vez tudo que já dá para perguntar, e só termina quando não
+sobra premissa adotada em silêncio. Junto veio a regra **fato é meu, decisão é sua** — o que dá
+para descobrir no repositório, no MCP ou no ambiente não vira pergunta ao dev.
+
+O `gates.json` virou **um arquivo por feature**, criado no brainstorm e alimentado até o verify
+(`spec_review` → `code_review` → `lint` → `deploy` → `qa_e2e`). `plan` e `implement` derivam o
+estágio **do arquivo**, nunca da conversa: sessão nova retoma de onde parou, e com mais de uma
+feature aberta o skill pergunta qual, em vez de escolher a mais recente.
+
+### Hook que barra a corrupção de acento antes dela acontecer
+
+`Edit`/`Write` em fonte CP-1252 liam o arquivo como UTF-8 e regravavam com os acentos já
+destruídos — o hook pós-gravação avisava depois do estrago. O novo **`advpl-encoding-pre.sh`**
+(PreToolUse) bloqueia a ferramenta antes da leitura destrutiva e entrega o script Python que
+edita preservando o charset. Coberto por testes na suíte.
+
+### Aprendizados de campo nas skills
+
+`writer` e `reviewer`: `FWMsgRun` dentro de `VALID` trava a tela; variável tipada compara com
+`Empty()`, não com `NIL` — e `advpls appre` **não** pega erro de tipo, então lint limpo não
+garante compilação. O `reviewer` também parou de reportar dois falsos positivos conhecidos em
+`.tlpp`. `patterns`: `MsUnlock` sempre com alias explícito, alias já posicionado após
+`Posicione()`, e PE bloqueante × PE pós-gravação. `query-builder`: `ORDER BY` com `DESC` por
+coluna e alias de subquery sem `AS` (Oracle). `mvc-generator`: MVC em `.tlpp` exige namespace
+completo + `U_` nas referências. `feedback`: checagem de duplicata/contradição antes do rascunho
+e tag `promote:<skill>` no payload.
+
+
 ## [2.7.0] — 2026-08-07
 
 ### Brainstorm em opus, implementação em sonnet, haiku só no deploy (protheus 2.15.0 · fluig 2.2.0)

README.md

@@ -5,7 +5,7 @@
 
 # DA DataAgile Agent Kit
 
-[![Versão](https://img.shields.io/badge/versão-2.7.0-1a4d5c?style=flat-square&logoColor=white)](https://github.com/tbc-servicos/dataagile-agent-kit/releases)
+[![Versão](https://img.shields.io/badge/versão-2.8.0-1a4d5c?style=flat-square&logoColor=white)](https://github.com/tbc-servicos/dataagile-agent-kit/releases)
 [![Claude Code](https://img.shields.io/badge/Claude_Code-plugin-CC785C?style=flat-square&logoColor=white)](https://claude.ai/code)
 [![Protheus](https://img.shields.io/badge/Protheus-ADVPL%2FTLPP-1a4d5c?style=flat-square&logoColor=white)](https://dataagile-agent-kit.dataagile.com.br)
 [![PO--UI MCP](https://img.shields.io/badge/PO--UI-MCP-22C55E?style=flat-square&logoColor=white)](https://po-ui.io)

protheus/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "protheus",
   "description": "Plugin Claude Code para desenvolvimento TOTVS Protheus — ciclo completo: brainstorm → plan → implement (teammates sonnet) → deploy (TDS-CLI) → qa (E2E Playwright) → verify. Geração ADVPL/TLPP, SQL embarcado, migração TLPP, diagnóstico, compilação, revisão, testes E2E Playwright (test-web), Knowledge Base MCP, integração TDN, geradores MVC/REST/query, dicionário de dados e geração de relatórios SmartView/TReports (smartview-relatorio).",
-  "version": "2.15.0",
+  "version": "2.16.0",
   "author": {
     "name": "TBC - Time de Desenvolvimento"
   },

protheus/CLAUDE.md

@@ -15,6 +15,7 @@ Para código com padrões TOTVS (notação húngara, BeginSQL, ExecBlock, MVC),
 | Quando você for... | Skill recomendada |
 |---|---|
 | Escrever/gerar código ADVPL ou TLPP | `/protheus:writer` |
+| Mapear o legado do cliente antes de mexer (customizações, PEs, regras) | `/protheus:arqueologia` |
 | Planejar uma feature ou novo desenvolvimento | `/protheus:brainstorm` |
 | Investigar erro, log de compilação, crash | `/protheus:diagnose` |
 | Revisar código existente | `/protheus:reviewer` |
@@ -36,7 +37,7 @@ Custo de código fora do padrão: alto (retrabalho, code review, manutenção).
 
 - **Notação húngara:** `c`=char · `n`=numérico · `l`=lógico · `d`=data · `a`=array · `b`=bloco · `o`=objeto
 - **Escopo explícito:** `Local` / `Static` / `Private` / `Public` — declarar no topo da função, antes de qualquer código
-- **Tratamento de erros:** programação defensiva com guard clauses e verificação de retorno; `ErrorBlock` para capturar erros de runtime em chamadas críticas; **nunca usar** `BEGIN SEQUENCE`
+- **Tratamento de erros (regra única):** programação defensiva com guard clauses e verificação de retorno; **`Try-Catch` é o padrão em TLPP** (`.tlpp`, classes); `ErrorBlock` **somente** em ADVPL clássico (`.prw`) onde Try-Catch não está disponível; **nunca usar** `BEGIN SEQUENCE`
 - **Extensões:** `.prw` programa · `.tlpp` TLPP moderno
 
 ## Regra de Modelos (OBRIGATÓRIA)
@@ -105,7 +106,11 @@ export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50
 
 ## Ciclo de Desenvolvimento
 
+> **Entrega de fonte ADVPL/TLPP roda pelos gates deste plugin.** Workflows genéricos
+> de entrega não passam por lint/compilação e não gravam `gates.json` — não use.
+
 ```
+/protheus:arqueologia → mapa do legado da fatia (quando não houver)
 /protheus:brainstorm → MIT044/design aprovado
 /protheus:plan       → plano de implementação com tasks tipadas
 /protheus:implement  → Agent Team (implementer sonnet + reviewers sonnet, worktree)

protheus/README.md

@@ -205,6 +205,7 @@ Reinicie o Claude Desktop depois de salvar.
 
 ```
 /protheus:init-project  → explora projeto, entrevista, gera CLAUDE.md
+/protheus:arqueologia   → mapa do legado da fatia (quando não houver)
 /protheus:brainstorm    → MIT044 (opcional) + perguntas + design aprovado
 /protheus:plan          → decompõe design em tasks ADVPL-tipadas
 /protheus:implement     → Agent Team (worktree + feedback bidirecional):
@@ -226,13 +227,14 @@ Reinicie o Claude Desktop depois de salvar.
 | Review e QA | **sonnet** | Análise qualitativa, padrões, riscos |
 | Deploy / compilação | **haiku** | Compilar e gerar patch — mecânico |
 
-## Skills Disponíveis (17)
+## Skills Disponíveis (18)
 
 ### Ciclo Principal
 
 | Comando | Descrição |
 |---------|-----------|
 | `/protheus:init-project` | Explora projeto, entrevista e gera `CLAUDE.md` |
+| `/protheus:arqueologia` | Mapeia a fatia do legado do cliente antes do design |
 | `/protheus:brainstorm` | Planeja implementação — MIT044, perguntas, design aprovado |
 | `/protheus:plan` | Decompõe design em tasks ADVPL-tipadas |
 | `/protheus:implement` | Agent Team: impl → spec-review → code-review → lint |
@@ -297,23 +299,20 @@ Acesso a referência pública ADVPL/TLPP filtrada por organização (row-level v
 | `searchFunction` | Busca funções ADVPL/TLPP por nome, módulo, tipo |
 | `findEndpoint` | Encontra endpoints REST por path, método |
 | `findSmartView` | Busca SmartView por keyword ou equipe |
-| `listModules` | Lista módulos com contagem de funções |
+| `searchKnowledge` | Busca padrões, templates, convenções e aprendizados registrados |
+| `submitFeedback` | Registra um aprendizado de correção na base (via `/protheus:feedback`) |
+| `get_skill` | Recupera o conteúdo de uma skill da base |
 | `ragSearchKnowledge` | Busca vetorial (embedding 1536-dim) sobre uma base de conhecimento técnico ADVPL/TLPP |
 | `ragSearchDocs` | Busca vetorial sobre documentação técnica TOTVS (TDN), retorna `title`+`source_url`+`product_id` |
 
 > Campos `source`, `implementation`, `code` (IP proprietário TOTVS) são removidos das respostas para tier external. A base RAG é uma curadoria técnica sem PII.
 
-### Tier `internal` (TBC — 9 tools)
+### Tools adicionais de tier interno
 
-Inclui as 4 do external + 5 internas adicionais:
-
-| Tool | Descrição |
-|------|-----------|
-| `findExecAuto` | Localiza chamadas ExecAuto por rotina ou tabela |
-| `findMvcPattern` | Busca padrões MVC por model_id ou tabela |
-| `searchByTable` | Cross-search por alias de tabela |
-| `searchKnowledge` | Busca padrões, templates e convenções |
-| `searchDocuments` | Busca nos documentos PDF de treinamento |
+Algumas tools extras (`findExecAuto`, `findMvcPattern`, `searchByTable`,
+`searchDocuments`, `listModules`) existem apenas para credenciais de tier interno —
+as skills as marcam com "(se disponível no seu tier)". Sem elas, o caminho
+equivalente é `ragSearchKnowledge`/`ragSearchDocs`.
 
 ## Deploy via TDS-CLI
 
@@ -356,8 +355,9 @@ saveLocal=/patches/
 protheus/
 ├── .mcp.json                      # config do MCP (aponta para start.sh)
 ├── CLAUDE.md                      # convenções + regra de modelos + Agent Teams
-├── skills/                        # 18 skills especializadas
+├── skills/                        # 19 skills especializadas
 │   ├── init-project/              # setup do projeto
+│   ├── arqueologia/               # mapa do legado da fatia
 │   ├── brainstorm/                # design aprovado
 │   ├── plan/                      # plano de implementação
 │   ├── implement/                 # orquestração Agent Team

protheus/hooks/advpl-encoding-pre.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# advpl-encoding-pre.sh — bloqueia Edit/Write em fonte CP-1252 ANTES da corrupção
+# Ativado por PreToolUse (Write|Edit)
+#
+# Por quê PRE e não só o advpl-encoding.sh (PostToolUse): quando o Edit lê um .prw
+# CP-1252 assumindo UTF-8, os bytes altos viram U+FFFD e o arquivo é regravado já
+# corrompido — o hook Post detecta, mas os acentos originais JÁ se perderam. Este
+# hook barra a ferramenta antes da leitura destrutiva. O advpl-encoding.sh
+# continua como rede de segurança pós-gravação.
+
+set -euo pipefail
+
+if ! command -v jq &>/dev/null; then
+  echo "⚠️  ENCODING(pre): jq não encontrado — verificação ignorada"
+  exit 0
+fi
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+# Sem caminho, arquivo novo (Write de arquivo inexistente) ou não-ADVPL: não interfere
+[[ -z "$FILE" || ! -f "$FILE" ]] && exit 0
+case "$FILE" in
+  *.prw|*.PRW|*.tlpp|*.TLPP) ;;
+  *) exit 0 ;;
+esac
+
+command -v python3 &>/dev/null || exit 0
+
+# Mesma detecção do advpl-encoding.sh: CP1252 = bytes altos que não decodificam UTF-8
+ENCODING_STATE=$(python3 - "$FILE" <<'PYEOF'
+import sys
+
+filepath = sys.argv[1]
+with open(filepath, 'rb') as f:
+    data = f.read()
+
+if not data or all(b < 128 for b in data):
+    print("ASCII")
+    sys.exit(0)
+
+if data.startswith(b'\xef\xbb\xbf'):
+    print("UTF8")
+    sys.exit(0)
+
+try:
+    data.decode('utf-8')
+    print("UTF8")
+except UnicodeDecodeError:
+    print("CP1252")
+PYEOF
+)
+
+if [[ "$ENCODING_STATE" == "CP1252" ]]; then
+  BASENAME=$(basename "$FILE")
+  cat >&2 <<EOMSG
+🚫 ENCODING: '$BASENAME' está em CP-1252 com acentos. Edit/Write leem UTF-8 e
+corromperiam os acentos em U+FFFD de forma IRREVERSÍVEL (o hook pós-gravação só
+avisaria depois do estrago).
+
+Edite via script Python preservando o charset (copie como está — heredoc e código
+na coluna 0):
+
+python3 - <<'PY'
+p = r'$FILE'
+s = open(p, encoding='cp1252', newline='').read()
+s = s.replace('<antigo>', '<novo>')
+open(p, 'w', encoding='cp1252', newline='').write(s)
+PY
+
+Confirme depois com: file "$FILE"  (deve reportar ISO-8859).
+EOMSG
+  exit 2
+fi
+
+exit 0

protheus/hooks/hooks.json

@@ -12,6 +12,18 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" advpl-encoding-pre.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Write|Edit",

protheus/hooks/session-context.cjs

@@ -12,13 +12,13 @@ emitSessionContext({
   profile: 'external',
   cleanupTbcDbs: true,
   groups: [
-    { title: 'Ciclo de desenvolvimento (nesta ordem)', names: ['init-project', 'brainstorm', 'plan', 'implement', 'deploy', 'qa', 'verify'] },
+    { title: 'Ciclo de desenvolvimento (nesta ordem)', names: ['init-project', 'arqueologia', 'brainstorm', 'plan', 'implement', 'deploy', 'qa', 'verify'] },
     { title: 'Geracao e revisao de codigo', names: ['writer', 'reviewer', 'compile', 'mvc-generator', 'tlpp-rest-endpoint-generator', 'query-builder', 'migrate'] },
     { title: 'Consulta e diagnostico', names: ['specialist', 'patterns', 'sql', 'data-dictionary-lookup', 'diagnose'] },
     { title: 'Testes e relatorios', names: ['test-web', 'smartview-relatorio', 'feedback'] },
   ],
   notes: [
-    'MCP tools disponiveis: searchFunction, findEndpoint, findSmartView, listModules (catalogo) + ragSearchKnowledge, ragSearchDocs (busca semantica) — plugin protheus tbc-knowledge',
+    'MCP tools disponiveis: searchFunction, findEndpoint, findSmartView, searchKnowledge, submitFeedback (catalogo) + ragSearchKnowledge, ragSearchDocs (busca semantica) — plugin protheus tbc-knowledge',
     'Regra de modelos: opus para brainstorm/design, sonnet para implementacao e review/QA, haiku somente para deploy/compilacao.',
   ],
 });