@fprad0/skill-master-mcp 1.0.0 → 1.0.1

package/docs/planning/mcp-1.0.0/00_RESUMO_EXECUTIVO_AUDITORIA_MENU.md

@@ -0,0 +1,118 @@
+# MCP 1.0.0 - Resumo Executivo da Auditoria do Menu
+
+Data da auditoria: 2026-06-30
+Pacote auditado: `@fprad0/skill-master-mcp@1.0.0`
+Diretorio testado: `C:\Users\CDT\Documents\F.Prado\skill-master-mcp-release-publish`
+
+## Objetivo
+
+Validar o `skill-master-menu` da versao `1.0.0`, testar as funcoes principais, identificar falhas reais e preparar planos de correcao avancados para a proxima iteracao do MCP Skill Master.
+
+O foco especial foi:
+
+- `Ativar skill aprendida no workspace`
+- `Ativar skill aprendida global`
+- confiabilidade do menu em Windows
+- qualidade visual cyberpunk pixel art
+- lentidao, UX ruim ou estados pouco claros
+
+## Resultado Geral
+
+O menu existe, abre via `--help`, `--status` e `--run`, renderiza frames cyberpunk nos comandos e possui 23 acoes registradas. A matriz oficial `npm run verify:menu` passou.
+
+O backend de ativacao de skill aprendida esta funcional. Testes isolados confirmaram que o core consegue ativar uma skill aprendida em alvo workspace e em alvo global temporario, criando:
+
+- `SKILL.md`
+- `skill-master-approval.json`
+
+Porem, as duas opcoes criticas do menu falham no modo `--run --yes`, porque o menu chama o subcomando interativo `--activate-interactive`. Em ambiente sem TTY, isso termina com:
+
+```text
+[skill_master] Interactive activation requires a TTY.
+```
+
+## Status por Area
+
+### Publicacao npm
+
+OK.
+
+```powershell
+npm view @fprad0/skill-master-mcp version --registry=https://registry.npmjs.org
+```
+
+Resultado:
+
+```text
+1.0.0
+```
+
+### Menu e acoes registradas
+
+OK.
+
+```powershell
+npm run verify:menu
+```
+
+Resultado:
+
+```text
+Menu action matrix OK.
+Actions: 23
+Required actions: 23
+```
+
+### Doctor
+
+Parcial.
+
+O doctor passou nos principais pontos, mas reportou Claude Code ausente neste computador:
+
+```text
+[NO] Claude Code opcional - ausente em claude CLI
+[NO] Readiness global - partial
+```
+
+Isso nao bloqueia Codex, Claude Desktop, Gemini ou Antigravity, que apareceram configurados.
+
+### Gate completo
+
+Falhou em Windows por expectativas POSIX nos testes:
+
+- `src/client-config.test.ts`
+- `src/project-skills.test.ts`
+
+Essas falhas precisam entrar como correcao obrigatoria antes da proxima release.
+
+### Ativacao de skill aprendida
+
+Core OK, menu com bug.
+
+O motor direto `activateSuccessSkillDraft` passou para workspace e global temporarios.
+
+O CLI direto `skill-master-success-skills --activate <manifest> --target <path> --yes` tambem passou.
+
+O menu falha quando executado assim:
+
+```powershell
+node bin\skill-master-menu.mjs --run activate-learned-local --yes
+node bin\skill-master-menu.mjs --run activate-learned-global --yes
+```
+
+## Prioridades de Correcao
+
+1. Corrigir `activateLearnedLocal` e `activateLearnedGlobal` para suportarem modo nao interativo com `--yes`.
+2. Corrigir testes cross-platform Windows/Linux/macOS.
+3. Melhorar UX de acoes interativas chamadas via `--run`, exibindo mensagem clara e alternativa automatizavel.
+4. Refinar estado visual do menu para mostrar acoes bloqueadas, interativas, destrutivas, seguras e recomendadas.
+5. Adicionar suite de regressao que cria drafts temporarios e valida ativacao local/global fim a fim.
+
+## Arquivos de Planejamento
+
+- `01_MATRIZ_TESTES_MENU_E_RESULTADOS.md`
+- `02_PLANO_CORRECAO_ATIVAR_SKILL_APRENDIDA.md`
+- `03_PLANO_COMPATIBILIDADE_WINDOWS_LINUX_MACOS.md`
+- `04_PLANO_UI_CYBERPUNK_PIXEL_ART_E_PERFORMANCE.md`
+- `05_PROMPT_TASK_EXECUCAO_CORRECOES.md`
+- `06_CHECKLIST_REGRESSAO_PRE_RELEASE.md`

package/docs/planning/mcp-1.0.0/01_MATRIZ_TESTES_MENU_E_RESULTADOS.md

@@ -0,0 +1,250 @@
+# MCP 1.0.0 - Matriz de Testes do skill-master-menu
+
+## Ambiente
+
+- Sistema: Windows
+- Shell: PowerShell
+- Pacote local: `@fprad0/skill-master-mcp@1.0.0`
+- Registry npm: `latest = 1.0.0`
+- Catalogo skill-master: 209 skills catalogadas
+- Global readiness reportado pelo `--status`: pronto
+- Doctor readiness: partial por Claude Code ausente
+
+## Comandos Executados
+
+### Skill Master catalogo
+
+```powershell
+skill_master_refresh_catalog(include_web=false)
+```
+
+Resultado:
+
+```text
+total: 209
+local: 143
+workspace: 66
+warnings: []
+```
+
+### Menu help
+
+```powershell
+node bin\skill-master-menu.mjs --help
+```
+
+Resultado: OK. Exibe 23 acoes disponiveis.
+
+Observacao: a lista e funcional, mas poderia marcar visualmente:
+
+- acao segura
+- acao interativa
+- acao que escreve arquivo
+- acao que precisa de `--yes`
+- acao nao indicada para pacote global
+
+### Menu status
+
+```powershell
+node bin\skill-master-menu.mjs --status
+```
+
+Resultado: OK.
+
+Resumo observado:
+
+```text
+Pacote: @fprad0/skill-master-mcp
+Semver local: 1.0.0
+Manifesto stable: 1.0.0
+Drafts de skills aprendidas: 0
+Skills externas para estudar: 8
+Global readiness: pronto
+Global skills instaladas: 25/25
+Codex MCP robusto: sim
+Claude MCP robusto: sim
+Gemini MCP robusto: sim
+Antigravity MCP robusto: sim
+```
+
+### Verificacao oficial de menu
+
+```powershell
+npm run verify:menu
+```
+
+Resultado: OK.
+
+```text
+Menu action matrix OK.
+```
+
+Limite do teste atual: ele valida existencia, aliases e confirmacoes, mas nao executa smoke real de todas as acoes.
+
+### Public npm
+
+```powershell
+node bin\skill-master-menu.mjs --run public-npm
+```
+
+Resultado: OK.
+
+```text
+1.0.0
+```
+
+### Activation status
+
+```powershell
+node bin\skill-master-menu.mjs --run activation-status
+```
+
+Resultado: OK.
+
+```text
+Modo: always-on-assisted
+```
+
+### Notifications
+
+```powershell
+node bin\skill-master-menu.mjs --run notifications
+```
+
+Resultado: OK.
+
+```text
+Drafts pendentes: 0
+Prontos para aprovacao humana: 0
+Skills externas para estudo: 8
+```
+
+### Study skills
+
+```powershell
+node bin\skill-master-menu.mjs --run study-skills
+```
+
+Resultado: OK.
+
+Observacao: lista 8 entradas. Tres entradas externas permanecem `unapproved` e devem continuar como estudo, nao ativacao.
+
+### Approval package
+
+Executado com diretorio temporario:
+
+```powershell
+$env:SKILL_MASTER_SUCCESS_LEARNING_DIR = Join-Path $env:TEMP 'skill-master-empty-success'
+node bin\skill-master-menu.mjs --run approval-package
+```
+
+Resultado: OK.
+
+Criou pacote com 0 drafts. A acao escreve arquivo, entao nao deve estar classificada como read-only na matriz de qualidade.
+
+### Doctor
+
+```powershell
+node bin\skill-master-menu.mjs --run doctor
+```
+
+Resultado: OK com alerta.
+
+```text
+[NO] Claude Code opcional - ausente em claude CLI
+[NO] Readiness global - partial
+```
+
+Recomendacao: distinguir melhor "partial por cliente opcional" de "falha operacional".
+
+### Build
+
+```powershell
+node bin\skill-master-menu.mjs --run build
+```
+
+Resultado: OK.
+
+### Check
+
+```powershell
+node bin\skill-master-menu.mjs --run check
+```
+
+Resultado: falhou por 2 testes Windows.
+
+Falhas:
+
+```text
+src/client-config.test.ts
+expected /opt/skill-master/bin/skill-master.mjs
+received \opt\skill-master\bin\skill-master.mjs
+
+src/project-skills.test.ts
+expected /tmp/app/.agents/skills
+received C:\tmp\app\.agents\skills
+```
+
+Classificacao: falha de teste cross-platform, nao falha de build.
+
+### Acoes protegidas sem --yes
+
+Exemplo:
+
+```powershell
+node bin\skill-master-menu.mjs --run install-global-skills
+node bin\skill-master-menu.mjs --run update-global
+node bin\skill-master-menu.mjs --run reject-skill
+```
+
+Resultado: OK, bloqueia sem `--yes`.
+
+```text
+Action <acao> requires --yes outside an interactive terminal.
+```
+
+### Prompt recommendation
+
+```powershell
+node bin\skill-master-menu.mjs --run prompt-router
+```
+
+Resultado: falha esperada fora de TTY.
+
+```text
+[skill_master] Interactive prompt routing requires a TTY.
+```
+
+Melhoria necessaria: oferecer `--prompt "..."` para uso nao interativo.
+
+### Ativar skill aprendida no workspace
+
+```powershell
+node bin\skill-master-menu.mjs --run activate-learned-local --yes
+```
+
+Resultado: falha.
+
+```text
+[skill_master] Interactive activation requires a TTY.
+```
+
+Classificacao: bug de menu.
+
+### Ativar skill aprendida global
+
+```powershell
+node bin\skill-master-menu.mjs --run activate-learned-global --yes
+```
+
+Resultado: falha.
+
+```text
+[skill_master] Interactive activation requires a TTY.
+```
+
+Classificacao: bug de menu.
+
+## Conclusao da Matriz
+
+O menu esta visualmente bom no modo `--run`, mas ainda mistura acoes interativas com automacao. O backend de skills aprendidas funciona, mas o menu nao expoe um caminho nao interativo completo para ativacao local/global.

package/docs/planning/mcp-1.0.0/02_PLANO_CORRECAO_ATIVAR_SKILL_APRENDIDA.md

@@ -0,0 +1,200 @@
+# MCP 1.0.0 - Plano de Correcao para Ativar Skill Aprendida
+
+## Problema
+
+As opcoes do menu:
+
+- `Ativar skill aprendida no workspace`
+- `Ativar skill aprendida global`
+
+falham quando chamadas via:
+
+```powershell
+node bin\skill-master-menu.mjs --run activate-learned-local --yes
+node bin\skill-master-menu.mjs --run activate-learned-global --yes
+```
+
+Erro observado:
+
+```text
+[skill_master] Interactive activation requires a TTY.
+```
+
+## Causa Raiz
+
+No `bin/lib/menu-core.mjs`, as acoes estao configuradas para chamar:
+
+```text
+skill-master-success-skills --activate-interactive --target local
+skill-master-success-skills --activate-interactive --target global
+```
+
+Mesmo quando o usuario passa `--yes` para o menu, o subcomando continua sendo interativo. Em ambiente Codex, CI ou qualquer execucao sem TTY, o comando falha antes de escolher o manifesto.
+
+O core nao esta quebrado. O teste isolado confirmou que:
+
+- `activateSuccessSkillDraft(...)` funciona
+- `skill-master-success-skills --activate <manifest> --target <path> --yes` funciona
+
+## Objetivo da Correcao
+
+Fazer as duas opcoes funcionarem em:
+
+1. menu visual interativo
+2. `skill-master-menu --run activate-learned-local`
+3. `skill-master-menu --run activate-learned-local --yes`
+4. `skill-master-menu --run activate-learned-global`
+5. `skill-master-menu --run activate-learned-global --yes`
+6. automacao com manifesto explicito
+7. Windows, Linux e macOS
+
+## Design Proposto
+
+### 1. Adicionar argumentos ao menu
+
+Adicionar suporte no `skill-master-menu`:
+
+```text
+--manifest <path>
+--target <local|global|path>
+--overwrite
+--reason <text>
+--prompt <text>
+```
+
+Para ativacao:
+
+```powershell
+skill-master-menu --run activate-learned-local --manifest C:\...\manifest.json --yes
+skill-master-menu --run activate-learned-global --manifest C:\...\manifest.json --yes
+```
+
+### 2. Adicionar modo auto-select seguro
+
+Quando `--yes` for usado sem `--manifest`, o menu deve:
+
+- listar drafts prontos para aprovacao humana
+- se houver 0, falhar com mensagem clara
+- se houver 1, ativar esse draft
+- se houver mais de 1, falhar pedindo `--manifest`
+
+Mensagem sugerida:
+
+```text
+[skill_master] Multiple ready learned skills found. Re-run with --manifest <path> or open the interactive menu.
+```
+
+### 3. Alterar acoes do menu
+
+No `buildMenuCommands`, trocar:
+
+```text
+--activate-interactive --target local
+--activate-interactive --target global
+```
+
+por um wrapper novo:
+
+```text
+--activate-menu --target local
+--activate-menu --target global
+```
+
+Ou, alternativamente, o proprio `skill-master-menu` resolve o manifesto e chama:
+
+```text
+skill-master-success-skills --activate <manifest> --target local --yes
+```
+
+### 4. Melhorar `skill-master-success-skills`
+
+Adicionar subcomando:
+
+```text
+skill-master-success-skills --activate-ready --target local|global --yes
+```
+
+Com regras:
+
+- 0 drafts prontos: erro claro
+- 1 draft pronto: ativa
+- mais de 1 draft pronto: erro claro com lista numerada e paths
+- global exige `--yes`
+- `--overwrite` deve ser explicito
+
+### 5. Preservar aprovacao humana
+
+Nao ativar drafts com:
+
+- `recommendation != ready-for-human-approval`
+- risk flags
+- external candidates unapproved
+- content hash divergente
+- nome duplicado no approved index
+
+### 6. Atualizar catalogo apos ativacao
+
+Apos ativar:
+
+```text
+skill_master_refresh_catalog(include_web=false)
+```
+
+Ou imprimir:
+
+```text
+Reinicie o cliente ou rode refresh do catalogo para a nova skill aparecer.
+```
+
+## Testes Obrigatorios
+
+### Unitarios
+
+Adicionar testes em `src/menu-core.test.ts`:
+
+- `activateLearnedLocal` deve ter caminho nao interativo quando receber manifest
+- `activateLearnedGlobal` deve ter caminho nao interativo quando receber manifest
+- `--yes` sem manifest e com 0 drafts retorna erro claro
+- `--yes` sem manifest e com 1 draft ativa
+- `--yes` sem manifest e com 2 drafts pede manifest
+
+### Integracao CLI
+
+Criar teste que:
+
+1. cria draft temporario com `prepareSuccessSkillDraft`
+2. chama `skill-master-menu --run activate-learned-local --manifest <path> --yes`
+3. valida `SKILL.md`
+4. valida `skill-master-approval.json`
+5. repete para global em `CODEX_HOME` temporario
+
+### Smoke manual
+
+Abrir:
+
+```powershell
+skill-master-menu
+```
+
+Validar:
+
+- frame de confirmacao aparece
+- selecao de draft aparece
+- ativacao local mostra destino
+- ativacao global mostra aviso de impacto
+- terminal volta ao estado normal apos sair
+
+## Definition of Done
+
+- `npm run build` passa
+- `npm test` passa no Windows
+- `npm run verify:menu` passa
+- `skill-master-menu --run activate-learned-local --manifest <path> --yes` passa
+- `skill-master-menu --run activate-learned-global --manifest <path> --yes` passa
+- menu interativo continua funcionando
+- nenhuma skill e ativada sem aprovacao humana ou `--yes`
+- documentacao `--help` mostra exemplos novos
+
+## Risco se Nao Corrigir
+
+O usuario ve a funcao no menu, acredita que esta pronta, mas ela falha exatamente no fluxo mais importante: promover aprendizado para skill local/global. Isso quebra a promessa central do Skill Master.