@fprad0/skill-master-mcp 0.0.12 → 1.0.1

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.

package/docs/planning/mcp-1.0.0/03_PLANO_COMPATIBILIDADE_WINDOWS_LINUX_MACOS.md

@@ -0,0 +1,167 @@
+# MCP 1.0.0 - Plano de Compatibilidade Windows, Linux e macOS
+
+## Problemas Encontrados
+
+O comando:
+
+```powershell
+node bin\skill-master-menu.mjs --run check
+```
+
+falhou em Windows com 2 testes.
+
+### Falha 1
+
+Arquivo:
+
+```text
+src/client-config.test.ts
+```
+
+Erro:
+
+```text
+expected /opt/skill-master/bin/skill-master.mjs
+received \opt\skill-master\bin\skill-master.mjs
+```
+
+### Falha 2
+
+Arquivo:
+
+```text
+src/project-skills.test.ts
+```
+
+Erro:
+
+```text
+expected /tmp/app/.agents/skills
+received C:\tmp\app\.agents\skills
+```
+
+## Causa Provavel
+
+Os testes usam caminhos POSIX como fixtures, mas o codigo usa APIs de path do sistema operacional atual. No Windows, `path.join` e `path.resolve` convertem para backslash ou prefixam drive.
+
+Isso cria falsos negativos em Windows.
+
+## Objetivo
+
+Garantir que:
+
+- testes passem em Windows, Linux e macOS
+- configs MCP usem o formato correto para cada cliente
+- caminhos de comando sejam robustos
+- caminhos serializados em TOML/JSON nao quebrem por escape
+- fixtures POSIX continuem testaveis no Windows quando necessario
+
+## Plano Tecnico
+
+### 1. Separar path operacional de path serializado
+
+Criar helpers claros:
+
+```ts
+toNativePath(value)
+toPosixPath(value)
+toJsonPath(value)
+toTomlPath(value)
+normalizePathForComparison(value)
+```
+
+Uso:
+
+- execucao local: native path
+- JSON/TOML de clientes: string absoluta segura
+- testes cross-platform: normalizacao explicita
+- fixtures POSIX: `path.posix`
+
+### 2. Corrigir teste Claude Code
+
+O teste que espera:
+
+```text
+/opt/skill-master/bin/skill-master.mjs
+```
+
+deve montar o server com path POSIX preservado ou comparar via normalizacao.
+
+Opcoes:
+
+1. Usar `path.posix.join` dentro do fixture.
+2. Comparar `normalizeSlashes(args[7])`.
+3. Ajustar `buildClaudeCodeAddArgs` para nao converter path que ja e POSIX absoluto.
+
+Recomendacao: preservar POSIX absoluto quando entrada comeca com `/`.
+
+### 3. Corrigir teste de roots do projeto
+
+O teste que usa `/tmp/app` deve:
+
+- rodar com `path.posix` se o objetivo e POSIX
+- ou aceitar resultado nativo se o objetivo e plataforma atual
+
+Recomendacao: dividir em dois testes:
+
+- `normalizes native project skill roots`
+- `preserves explicit POSIX roots when requested`
+
+### 4. Adicionar matriz de CI local
+
+Scripts sugeridos:
+
+```json
+{
+  "test:windows-paths": "vitest run src/client-config.test.ts src/project-skills.test.ts",
+  "test:menu": "node scripts/verify-menu-actions.mjs",
+  "test:activation-cli": "vitest run src/success-learning.test.ts src/menu-core.test.ts"
+}
+```
+
+### 5. Validar instalacao global 1.0.0
+
+Comandos:
+
+```powershell
+npm install -g @fprad0/skill-master-mcp@1.0.0 --registry=https://registry.npmjs.org
+where skill-master-menu
+skill-master-menu --status
+skill-master-doctor
+```
+
+No Linux/macOS:
+
+```bash
+npm install -g @fprad0/skill-master-mcp@1.0.0 --registry=https://registry.npmjs.org
+command -v skill-master-menu
+skill-master-menu --status
+skill-master-doctor
+```
+
+## Melhorias no Doctor
+
+Hoje o doctor retorna `partial` quando Claude Code esta ausente. Isso pode assustar quando o usuario nao usa Claude Code.
+
+Melhoria:
+
+- separar clientes obrigatorios de opcionais
+- exibir `ready-with-optional-warnings`
+- retornar exit code 0 quando apenas cliente opcional estiver ausente
+
+Estados sugeridos:
+
+```text
+ready
+ready_with_optional_warnings
+partial
+blocked
+```
+
+## Definition of Done
+
+- `npm run check` passa no Windows
+- testes continuam passando em Linux/macOS
+- doctor distingue cliente opcional ausente de falha real
+- registro Codex, Claude Desktop, Gemini e Antigravity permanece com node absoluto
+- nenhum teste usa expectativa POSIX acidental em Windows