@polymorphism-tech/morph-spec 4.8.1 → 4.8.4

package/docs/plans/2026-02-24-cli-radical-simplification.md

@@ -1,592 +0,0 @@
-# CLI Radical Simplification Plan
-
-**Status:** COMPLETE
-
-> **For Claude:** REQUIRED SUB-SKILL: Use `superpowers:executing-plans` to implement this plan task-by-task.
-
-**Goal:** Reduzir a superfície CLI para apenas comandos chamados internamente pelo framework (hooks/skills/outros comandos), mantendo `doctor`, `init` e `update` como únicos comandos de usuário. Remover ~25 comandos e arquivos de lib orfãos.
-
-**Architecture:** Remoção em fases: (1) integração de `markOutput` no recap-generator via TDD, (2) limpeza de bin/morph-spec.js, (3) deleção de arquivos de comando, (4) remoção de código morto em arquivos que ficam, (5) limpeza de libs e testes orfãos, (6) verificação da suite.
-
-**Tech Stack:** Node.js ESM, Commander.js, node:test
-
----
-
-## Princípio de decisão
-
-| Categoria | Critério | Ação |
-|-----------|----------|------|
-| User-facing (permitido) | `doctor`, `init`, `update` | Manter |
-| Framework-internal | Chamado por hook, skill ou outro comando CLI | Manter |
-| Deveria ser chamado mas não é | Gap de integração | Integrar automaticamente |
-| Nunca chamado por ninguém | Dead code | Remover |
-
----
-
-## Mapa final: o que fica
-
-```
-bin/morph-spec.js registra apenas:
-  init              ← user
-  update            ← user
-  doctor            ← user
-  state             ← framework (init/get/set/list/mark-output/add-agent/remove-agent)
-  validate-phase    ← framework (chamado por phase advance)
-  phase advance     ← framework (skills + dispatch.js)
-  task done/start/next  ← framework (skills + dispatch.js)
-  approve           ← framework (dispatch.js + skills)
-  approval-status   ← framework (skills)
-  validate          ← framework (verification-before-completion skill)
-  validate-feature  ← framework (chamado por task done)
-  checkpoint-save/restore/list ← framework (dispatch.js + skills)
-  mcp setup         ← framework (chamado por init)
-  template render   ← framework (skills de fase)
-  trust set/status  ← framework (futuro: skill de configuração)
-  generate recap    ← framework (phase-implement skill)
-```
-
----
-
-## Task 1: TDD — markOutput automático no recap-generator
-
-**Por quê primeiro:** Única mudança de comportamento do plano. Feita antes da limpeza para garantir que não quebramos nada.
-
-**Files:**
-- Modify: `src/lib/generators/recap-generator.js`
-- Test: `test/lib/recap-generator.test.js` (criar se não existir)
-
-**Step 1: Verificar se o arquivo de teste existe**
-
-```bash
-node -e "require('fs').existsSync('test/lib/recap-generator.test.js') && console.log('exists')"
-```
-
-Se não existir, criar o arquivo na próxima etapa.
-
-**Step 2: Escrever o teste que falha**
-
-Em `test/lib/recap-generator.test.js`, adicionar:
-
-```javascript
-import { describe, it, mock, beforeEach } from 'node:test';
-import assert from 'node:assert/strict';
-
-describe('generateRecap - markOutput integration', () => {
-  it('calls markOutput with "recap" after writing the file', async () => {
-    // Arrange: mock state-manager and validation-runner
-    const calls = [];
-
-    // We'll test this via the exported function's side effects
-    // Verify markOutput is imported and called
-    const { generateRecap } = await import('../../src/lib/generators/recap-generator.js');
-    assert.ok(typeof generateRecap === 'function', 'generateRecap should be exported');
-  });
-});
-```
-
-**Step 3: Verificar que o teste roda**
-
-```bash
-node --test test/lib/recap-generator.test.js
-```
-
-**Step 4: Adicionar import de markOutput em recap-generator.js**
-
-Localizar linha 13 em `src/lib/generators/recap-generator.js`:
-```javascript
-import { loadState } from '../../core/state/state-manager.js';
-```
-
-Trocar por:
-```javascript
-import { loadState, markOutput } from '../../core/state/state-manager.js';
-```
-
-**Step 5: Chamar markOutput após gravar o arquivo**
-
-Localizar onde `writeFileSync(recapPath, recapContent)` é chamado (ou onde o recap é salvo) e adicionar após:
-
-```javascript
-// Auto-mark recap output as created in state
-try {
-  await markOutput(featureName, 'recap');
-} catch {
-  // Non-fatal: state may not exist in all contexts
-}
-```
-
-**Step 6: Rodar suite completa**
-
-```bash
-node --test
-```
-
-Expected: mesma quantidade de passes que antes (sem regressões).
-
-**Step 7: Commit**
-
-```bash
-git add src/lib/generators/recap-generator.js test/lib/recap-generator.test.js
-git commit -m "feat(recap): auto-call markOutput after generating recap.md"
-```
-
----
-
-## Task 2: Limpar bin/morph-spec.js — remover imports e registros
-
-**Files:**
-- Modify: `bin/morph-spec.js`
-
-Esta é a mudança mais longa: remover ~35 linhas de imports e ~150 linhas de registros de comando.
-
-**Step 1: Remover imports de comandos sendo deletados**
-
-Encontrar e remover os seguintes blocos de import em `bin/morph-spec.js`:
-
-```javascript
-// REMOVER — update-agents
-import { updateAgentsCommand } from '../src/commands/project/update-agents.js';
-
-// REMOVER — sync
-import { syncCommand } from '../src/commands/project/sync.js';
-
-// REMOVER — changes
-import { changesCommand } from '../src/commands/project/changes.js';
-
-// REMOVER — story commands (feature/)
-import { createStoryCommand } from '../src/commands/feature/create-story.js';
-import { shardSpecCommand } from '../src/commands/feature/shard-spec.js';
-import { sprintStatusCommand } from '../src/commands/feature/sprint-status.js';
-
-// REMOVER — rollback
-import { rollbackPhaseCommand } from '../src/commands/state/rollback-phase.js';
-
-// REMOVER — reject (manter approve + approvalStatus)
-// Alterar: import { approveCommand, rejectCommand, approvalStatusCommand }
-// Para:    import { approveCommand, approvalStatusCommand }
-
-// REMOVER — generate design-system e metadata (manter apenas recap)
-// Alterar: import { generateDesignSystemCommand, generateMetadataCommand }
-// Para:    (sem import desses dois — gerarRecap vem do lib direto)
-
-// REMOVER — generate onboarding
-import { generateOnboardingCommand } from '../src/commands/generation/generate-onboarding.js';
-
-// REMOVER — validate-blazor, lint-fluent, analyze-blazor-concurrency, validate-blazor-state, validate-css
-import { validateBlazorCommand } from '../src/commands/validation/validate-blazor.js';
-import { lintFluentCommand } from '../src/commands/validation/lint-fluent.js';
-import { analyzeBlazorConcurrencyCommand } from '../src/commands/validation/analyze-blazor-concurrency.js';
-import { validateBlazorStateCommand } from '../src/commands/validation/validate-blazor-state.js';
-import { validateCssCommand } from '../src/commands/validation/validate-css.js';
-
-// REMOVER — template list/show/customize/validate (manter render)
-import { templateListCommand } from '../src/commands/templates/template-list.js';
-import { templateShowCommand } from '../src/commands/templates/template-show.js';
-import { templateCustomizeCommand } from '../src/commands/templates/template-customize.js';
-import { templateValidateCommand } from '../src/commands/templates/template-validate.js';
-
-// REMOVER — learning (capturePatternProgram, searchPatternsProgram)
-import capturePatternProgram from '../src/commands/learning/capture-pattern.js';
-import searchPatternsProgram from '../src/commands/learning/search-patterns.js';
-
-// REMOVER — troubleshoot
-import troubleshootCommand from '../src/commands/utils/troubleshoot.js';
-
-// REMOVER — mcp optimize/list (manter mcpSetupCommand)
-import { mcpOptimizeCommand, mcpListCommand } from '../src/commands/mcp/mcp.js';
-
-// REMOVER — trust history/auto-calculate/clear (manter status + set)
-// Alterar: import { trustStatusCommand, trustSetCommand, trustHistoryCommand, trustAutoCalculateCommand, trustClearCommand }
-// Para:    import { trustStatusCommand, trustSetCommand }
-
-// REMOVER — LearningSystem class (era usado por learn commands)
-import { LearningSystem } from '../src/lib/learning/learning-system.js';
-
-// REMOVER — diff/diff-save, cost, revert, checkpoint-* para checkpoint-save/restore/list
-import { diffCommand, diffSaveCommand } from '../src/commands/project/diff.js';
-import { costCommand } from '../src/commands/project/cost.js';
-import { revertCommand } from '../src/commands/project/revert.js';
-```
-
-**Step 2: Remover registros de comando em bin/morph-spec.js**
-
-Remover os seguintes blocos `program.command(...)` e `storyCommand/learnCommand/mcpCommand` sub-commands:
-
-- Bloco `update-agents` (~4 linhas)
-- Bloco `sync` (~5 linhas)
-- Bloco `changes` (~4 linhas)
-- Bloco `story` completo — incluindo `storyCommand` const + create + shard + status (~25 linhas)
-- Bloco `rollback` (~6 linhas)
-- Bloco `reject` (~4 linhas) — manter `approve` e `approval-status`
-- Bloco `generate design-system` (~15 linhas) — manter apenas `generate recap`
-- Bloco `generate metadata` (~8 linhas)
-- Bloco `generate onboarding` (~4 linhas)
-- Bloco `validate-blazor` (~5 linhas)
-- Bloco `lint-fluent` (~5 linhas)
-- Bloco `analyze-blazor-concurrency` (~5 linhas)
-- Bloco `validate-blazor-state` (~5 linhas)
-- Bloco `validate-css` (~8 linhas)
-- Blocos `learn` completo — incluindo `learnCommand` const + analyze + insights + suggest + reset (~60 linhas)
-- Bloco `standards` (~18 linhas)
-- Blocos `template list/show/customize/validate` (~40 linhas) — manter `template render`
-- Blocos `trust history/auto-calculate/clear` (~15 linhas) — manter `trust status` e `trust set`
-- Bloco `troubleshoot` (~8 linhas)
-- `mcpCommand.command('optimize')` + `mcpCommand.command('list')` (~8 linhas) — manter `mcp setup`
-- `program.addCommand(capturePatternProgram)` (~1 linha)
-- `program.addCommand(searchPatternsProgram)` (~1 linha)
-- Blocos `diff/diff-save` (~8 linhas)
-- Bloco `cost` (~5 linhas)
-- Bloco `revert` (~6 linhas)
-
-**Step 3: Verificar que bin ainda funciona**
-
-```bash
-node bin/morph-spec.js --help
-```
-
-Expected: help menu sem erros; apenas comandos mantidos listados.
-
-**Step 4: Rodar suite**
-
-```bash
-node --test
-```
-
-Expected: mesma quantidade de passes. Se houver falhas por imports quebrados, verificar se algum import foi esquecido.
-
-**Step 5: Commit**
-
-```bash
-git add bin/morph-spec.js
-git commit -m "refactor(cli): remove 25+ user-facing commands from CLI surface"
-```
-
----
-
-## Task 3: Deletar arquivos de comando removidos
-
-**Files to DELETE (use `git rm` para cada um):**
-
-```bash
-# Feature commands
-git rm src/commands/feature/create-story.js
-git rm src/commands/feature/shard-spec.js
-git rm src/commands/feature/sprint-status.js
-git rm src/commands/feature/index.js
-
-# Project commands
-git rm src/commands/project/update-agents.js
-git rm src/commands/project/sync.js
-git rm src/commands/project/changes.js
-git rm src/commands/project/diff.js
-git rm src/commands/project/cost.js
-git rm src/commands/project/revert.js
-git rm src/commands/project/standards.js
-
-# State commands
-git rm src/commands/state/rollback-phase.js
-
-# Validation commands (standalone wrappers — libs ficam)
-git rm src/commands/validation/validate-blazor.js
-git rm src/commands/validation/validate-blazor-state.js
-git rm src/commands/validation/validate-css.js
-git rm src/commands/validation/lint-fluent.js
-git rm src/commands/validation/analyze-blazor-concurrency.js
-
-# Template commands (manter render)
-git rm src/commands/templates/template-list.js
-git rm src/commands/templates/template-show.js
-git rm src/commands/templates/template-customize.js
-git rm src/commands/templates/template-validate.js
-
-# Utils + learning
-git rm src/commands/utils/troubleshoot.js
-git rm src/commands/learning/capture-pattern.js
-git rm src/commands/learning/search-patterns.js
-git rm src/commands/learning/index.js
-
-# MCP (apenas optimize/list)
-git rm src/commands/mcp/mcp.js
-
-# Generation (manter recap via lib; remover generate.js que tinha design-system/metadata)
-git rm src/commands/generation/generate-onboarding.js
-```
-
-**Nota sobre generate.js:** Este arquivo contém `generateDesignSystemCommand` e `generateMetadataCommand`. Como `generate recap` vai diretamente para a lib (`recap-generator.js`), o arquivo `generate.js` (que tinha design-system e metadata) pode ser deletado inteiro:
-
-```bash
-git rm src/commands/generation/generate.js
-```
-
-E em `bin/morph-spec.js`, o subcommand `generate recap` já invoca `generateRecap` do lib diretamente (via dynamic import inline), então não precisa de import de `generate.js`.
-
-**Nota sobre generate-onboarding.js:** Deletado acima.
-
-**Nota sobre generation/index.js:** Verificar se ainda é usado após remover generate.js e generate-onboarding.js:
-```bash
-grep -r "generation/index" bin/ src/ --include="*.js"
-```
-Se nenhum resultado → deletar:
-```bash
-git rm src/commands/generation/index.js
-```
-
-**Step 1: Executar todos os `git rm` acima**
-
-**Step 2: Rodar suite**
-
-```bash
-node --test
-```
-
-Expected: sem novas falhas. Se algum arquivo deletado ainda era importado em algum test, a falha apontará o arquivo.
-
-**Step 3: Commit**
-
-```bash
-git add -A
-git commit -m "refactor(cli): delete source files for removed commands"
-```
-
----
-
-## Task 4: Slim down arquivos que ficam (remover código morto interno)
-
-### 4a: `src/commands/state/approve.js` — remover rejectCommand
-
-**File:** `src/commands/state/approve.js`
-
-Remover:
-1. A função `rejectCommand` (export async function rejectCommand...)
-2. O bloco que registra o comando `reject` no Commander program interno do arquivo (`program.command('reject ...')`)
-
-Manter: `approveCommand`, `approvalStatusCommand`, e as importações que eles usam.
-
-**Verificar que o arquivo ainda exporta corretamente:**
-```bash
-node -e "import('./src/commands/state/approve.js').then(m => console.log(Object.keys(m)))"
-```
-Expected: `['approveCommand', 'approvalStatusCommand', 'default']` (sem rejectCommand)
-
-### 4b: `src/commands/state/state.js` — remover case 'checkpoint'
-
-**File:** `src/commands/state/state.js`
-
-Localizar o case `'checkpoint'` no switch/router (linha ~34):
-```javascript
-case 'checkpoint':
-  await checkpointCommand(args[0], args.slice(1).join(' '), options);
-  break;
-```
-E a função `checkpointCommand` (linha ~194).
-
-Remover ambos. Atualizar o help text na linha ~58 para remover "checkpoint" da lista.
-
-### 4c: `src/commands/trust/trust.js` — remover history/auto-calculate/clear
-
-**File:** `src/commands/trust/trust.js`
-
-Remover as funções:
-- `trustHistoryCommand` (linha ~121)
-- `trustAutoCalculateCommand` (linha ~156)
-- `trustClearCommand` (linha ~196)
-
-Manter: `trustStatusCommand`, `trustSetCommand`.
-
-Remover imports que só eram usados por essas funções (se houver).
-
-### 4d: `src/commands/generation/generate.js` — verificação (já foi deletado na Task 3)
-
-Se o arquivo foi deletado, pular. Se ainda existe com apenas código de design-system/metadata, confirmar a deleção.
-
-**Step: Rodar suite após todas as alterações do Task 4**
-
-```bash
-node --test
-```
-
-**Step: Commit**
-
-```bash
-git add src/commands/state/approve.js src/commands/state/state.js src/commands/trust/trust.js
-git commit -m "refactor(cli): remove dead code from approve.js, state.js, trust.js"
-```
-
----
-
-## Task 5: Deletar lib files orfãos
-
-**Files to DELETE:**
-
-```bash
-# Troubleshooting lib — só usado por troubleshoot.js (deletado)
-git rm src/lib/troubleshooting/troubleshoot-grep.js
-git rm src/lib/troubleshooting/troubleshoot-index.js
-```
-
-Verificar se o diretório troubleshooting ainda tem outros arquivos:
-```bash
-ls src/lib/troubleshooting/
-```
-Se vazio (ou só index.js que re-exportava os dois), deletar o diretório também:
-```bash
-git rm src/lib/troubleshooting/index.js
-# ou rmdir via git rm -r
-```
-
-```bash
-# Conversation analyzer — só usado por sync.js (deletado)
-git rm src/lib/detectors/conversation-analyzer.js
-```
-
-Verificar se detectors/index.js ainda re-exporta conversation-analyzer:
-```bash
-grep "conversation-analyzer" src/lib/detectors/index.js
-```
-Se sim, remover essa linha do index.js.
-
-**Nota: NÃO deletar:**
-- `src/lib/generators/design-system-generator.js` — usado por `design-system-validator.js` e testes
-- `src/lib/generators/metadata-extractor.js` — usado por testes de integração
-- `src/lib/validators/blazor/` — usado por `validation-runner.js` via registry
-- `src/lib/learning/learning-system.js` — verificar se é usado por algo além dos learning commands
-
-**Verificar learning-system.js:**
-```bash
-grep -r "learning-system" src/ bin/ --include="*.js" | grep -v "learning/capture\|learning/search\|learning/index"
-```
-Se nenhum resultado além dos arquivos já deletados → deletar:
-```bash
-git rm src/lib/learning/learning-system.js
-```
-Verificar se há outros arquivos em `src/lib/learning/`:
-```bash
-ls src/lib/learning/
-```
-Deletar todos os orfãos.
-
-**Step: Rodar suite**
-
-```bash
-node --test
-```
-
-**Step: Commit**
-
-```bash
-git add -A
-git commit -m "refactor(cli): delete orphaned lib files (troubleshooting, learning, conversation-analyzer)"
-```
-
----
-
-## Task 6: Deletar test files orfãos + corrigir imports quebrados
-
-**Files to DELETE:**
-
-```bash
-git rm test/commands/standards.test.js
-git rm test/commands/update-agents.test.js
-```
-
-**Verificar outros arquivos de teste com imports para arquivos deletados:**
-
-```bash
-node --test 2>&1 | grep "ERR_MODULE_NOT_FOUND\|Cannot find"
-```
-
-Para cada erro encontrado, localizar o arquivo de teste e:
-- Se o teste é exclusivo do comando deletado → `git rm` o arquivo
-- Se o teste tem outras assertions válidas → remover apenas o import/bloco referente ao comando deletado
-
-**Verificar `test/integration/v3-full-workflow.test.js`:**
-Este arquivo importa `searchPatternsCommand`. Remover esse import e qualquer assertion que dependa dele.
-
-```bash
-grep -n "searchPatterns\|capture-pattern\|LearningSystem" test/integration/v3-full-workflow.test.js
-```
-
-Remover as linhas encontradas.
-
-**Step: Rodar suite completa**
-
-```bash
-node --test
-```
-
-Expected: 0 falhas relacionadas a arquivos deletados. Total de testes pode cair (tests deletados), mas nenhum teste válido deve quebrar.
-
-**Step: Commit**
-
-```bash
-git add -A
-git commit -m "test: remove test files for deleted CLI commands"
-```
-
----
-
-## Task 7: Verificação final e atualização de documentação
-
-**Step 1: Rodar suite completa e capturar resultado**
-
-```bash
-node --test 2>&1 | tail -5
-```
-
-Expected:
-- Todos os testes existentes passando
-- Contagem de testes menor (removemos arquivos de teste)
-- 0 falhas novas
-
-**Step 2: Verificar CLI surface**
-
-```bash
-node bin/morph-spec.js --help
-```
-
-Expected: apenas os comandos mantidos visíveis.
-
-**Step 3: Verificar comandos específicos ainda funcionam**
-
-```bash
-node bin/morph-spec.js state --help
-node bin/morph-spec.js task --help
-node bin/morph-spec.js generate --help
-node bin/morph-spec.js template --help
-node bin/morph-spec.js trust --help
-node bin/morph-spec.js mcp --help
-```
-
-**Step 4: Atualizar CHEATSHEET e README**
-
-Remover referências aos comandos deletados em:
-- `docs/CHEATSHEET.md`
-- `README.md`
-
-Não criar nova documentação — apenas remover entradas dos comandos deletados.
-
-**Step 5: Commit final**
-
-```bash
-git add docs/CHEATSHEET.md README.md
-git commit -m "docs: remove documentation for deleted CLI commands"
-```
-
----
-
-## Resumo: o que muda
-
-### Comandos removidos (~25)
-`update-agents`, `sync`, `changes`, `story create/shard/status`, `rollback`, `reject`, `generate design-system`, `generate metadata`, `generate onboarding`, `validate-blazor`, `validate-blazor-state`, `validate-css`, `lint-fluent`, `analyze-blazor-concurrency`, `template list/show/customize/validate`, `standards`, `trust history/auto-calculate/clear`, `troubleshoot`, `mcp optimize/list`, `learn *`, `capture-pattern`, `search-patterns`, `diff/diff-save`, `cost`, `revert`, `state checkpoint`
-
-### Arquivos de comando deletados (~24 arquivos)
-Ver Task 3.
-
-### Lib files deletados (~3-5 arquivos)
-`troubleshoot-grep.js`, `troubleshoot-index.js`, `conversation-analyzer.js`, arquivos de `src/lib/learning/`
-
-### Integração adicionada (1)
-`recap-generator.js` → auto-chama `markOutput('recap')` após gravar arquivo
-
-### Comportamento idêntico para o framework
-Todos os comandos chamados por hooks, skills e outros comandos continuam funcionando exatamente como antes.