ai-dev-workflow-cli 0.0.0-stage → 0.5.0

package/docs/DISCOVERY_CLI.md

@@ -0,0 +1,83 @@
+# Discovery estático — TASK-006
+
+Disponível na CLI 0.5.0 (introduzido na 0.3.0), Node.js 24 exclusivo da ferramenta; sem dependências npm. O comando `discover` analisa arquivos estáticos autorizados, sem executar código da aplicação ou acessar rede/banco. Sem --save, não preenche DISCOVERY.md; não concede G1 e não substitui revisão humana. Discover não altera template, manifestos ou snapshots de instalação do alvo; a versão do template padrão é documentada no guia multi-IA.
+
+## Uso
+```sh
+node /caminho/ai-dev-workflow/bin/ai-dev-workflow.js discover --target /caminho/projeto
+node /caminho/ai-dev-workflow/bin/ai-dev-workflow.js discover --target /caminho/projeto --json
+node /caminho/ai-dev-workflow/bin/ai-dev-workflow.js discover --target /caminho/projeto --dry-run --json
+node /caminho/ai-dev-workflow/bin/ai-dev-workflow.js discover --target /caminho/sem-git --allow-no-git --json
+```
+No PowerShell, use caminhos absolutos Windows entre aspas nos mesmos argumentos. Esses exemplos não comprovam compatibilidade Windows. Nenhuma permissão chmod é necessária para execução explícita via node.
+
+Saída texto por padrão, JSON único em stdout com --json. Não há --output nem gravação sem --save; --dry-run continua realizando a análise readonly, sem criar lock, journal, manifesto ou relatório. --track não é aceito. --allow-no-git é exclusivo de discover e só permite ausência real de .git local, sem Git pai detectado. Git inválido/inseguro nunca tem fallback. Executável Git indisponível em projeto com Git é erro operacional; sem Git ele não é necessário. Código 0 significa análise concluída dentro da cobertura limitada, não aplicação validada.
+
+## Git e isolamento
+Discover aceita qualquer branch, inclusive main/master, unborn válido e HEAD destacado com commit válido. Mantém inspeção completa dos caminhos/metadados Git antes das consultas fixas, sem hooks, rede, configs globais ou escrita. Worktrees, gitfiles, repositórios pai/aninhados e armazenamento indireto continuam bloqueados. Init e doctor mantêm suas restrições anteriores, inclusive main/master e HEAD destacado. Não há git init, checkout ou reparo automático.
+
+Sem Git, exigir --allow-no-git: a raiz fornecida é o limite autorizado, não identidade do projeto comprovada. Branch/commit permanecem desconhecidos. A checagem de pais consulta apenas existência de marcadores .git para evitar analisar uma subpasta como projeto independente; não carrega conteúdo desses pais. Módulos filhos com marcador .git são excluídos sem ler esse marcador. O usuário deve selecionar o destino correto.
+
+Links/junctions, ancestrais arbitrariamente redirecionados, hardlinks e arquivos especiais em candidatos são bloqueados antes de ler conteúdo. Exceções de aliases de sistema macOS seguem o contrato existente. Não há seguimento de includes, imports, env_file, URLs ou caminhos de dependências. Permissões/ACLs e filesystem estável são necessários; não se promete proteção absoluta contra processo hostil trocando diretórios, mounts ou conteúdo durante a análise.
+
+## Cobertura bounded-static-v1
+Somente candidatos explícitos na raiz e em módulos diretamente sob apps/, packages/ e services/. Sem busca recursiva livre, inferência de todos os workspaces ou leitura de vendor/node_modules/payloads/templates do workflow. Diretórios backend/frontend na raiz não são percorridos automaticamente nesta versão.
+
+| Área | Suporte inicial e limites |
+| --- | --- |
+| Node.js | package.json: engines, packageManager npm/pnpm/yarn/bun e dependências conhecidas Next/React/Vue/Nuxt/Angular/Express/Fastify/Nest; package-lock resolve versões desses frameworks. pnpm-lock.yaml/yarn.lock/bun.lock identificam presença do gerenciador, sem resolução interna. .nvmrc/.node-version reconhecem versões numéricas limitadas. |
+| PHP | composer.json/lock: requisito PHP, Composer, Laravel/Symfony/Slim/CakePHP e drivers conhecidos. Não lê arquivos PHP/config/database.php ou executa Artisan. |
+| Python | pyproject.toml, requirements.txt, poetry.lock, Pipfile.lock; marcadores de gerenciador e indícios textuais Django/Flask/FastAPI; requires-python simples. Sem parser TOML completo ou execução Python. |
+| Java/JVM | pom.xml, build.gradle/build.gradle.kts; Maven/Gradle, indícios Spring e alvo Java em tags XML estáticas conhecidas. Não avalia Gradle, propriedades ou XML externo. |
+| Ruby | Gemfile/Gemfile.lock/.ruby-version; Ruby/Bundler e indícios Rails. Não avalia Ruby nem resolve dependências. |
+| Banco | Drivers conhecidos em manifestos e imagens simples mysql/mariadb/postgres/mongo/redis; seleção e servidor ativos sempre desconhecidos. Não lê .env, URLs de conexão ou configurações PHP. |
+| Docker | Dockerfile, compose.yml/yaml, docker-compose.yml/yaml; FROM/image simples de produtos conhecidos. Sem interpolação, registro privado, includes ou parser YAML completo; nenhuma imagem é consultada. Contextos e fallback conservador da TASK-006.1 descritos abaixo. |
+| CI/CD | Presença de arquivos .github/workflows/*.yml/yaml, .gitlab-ci.yml e Jenkinsfile. Conteúdo de CI não é lido; jobs, deploy, execução e sucesso não são comprovados. |
+
+Limites: 256 arquivos lidos, 2 MiB por arquivo, 8 MiB totais, 64 entradas nos contêineres de módulos e 256 entradas no diretório GitHub workflows. Limites de metadados Git permanecem os anteriores. Ultrapassar um limite bloqueia com exit 2, sem relatório de sucesso incompleto. Nomes de módulo não suportados e repositórios filhos excluídos geram diagnósticos; coverage.partial sinaliza diagnósticos. Arquivos ausentes não certificam ausência de tecnologia. Formatos e diretórios fora da lista não são inspecionados.
+
+## Evidências e privacidade
+reportVersion 1.0.0 contém mode, head (estado, não nome da branch), readOnly, databasePolicy, coverage, observations e diagnostics. Cada observação inclui category/name/value, classification, basis e evidence com caminho relativo e linha quando localizável, ou locator de presença. As linhas são localizadores aproximados para regras textuais e chaves repetidas, não prova semântica de parser completo.
+
+- confirmado: fato declarado no arquivo, como requisito ou versão de lock; não significa runtime instalado.
+- inferido: indício textual, framework ou possibilidade de banco por driver; pode ser falso positivo, inclusive em comentários/exemplos.
+- desconhecido: runtime instalado, banco ativo, execução da CI e conclusões sem evidência suportada.
+
+Requisitos e versões diferentes são mantidos como evidências separadas; MULTIPLE_VERSION_EVIDENCE pede revisão, não afirma incompatibilidade (um range e uma versão podem ser compatíveis). Valores de versão só admitem subconjunto numérico de constraints; outros valores ficam nulos. Relatório não inclui conteúdo bruto, scripts, URLs, nomes arbitrários de dependências ou erros de parser. Arquivos de credenciais (.env/.npmrc/chaves/dumps) não são candidatos. Manifestos e Compose podem conter valores sensíveis incidentais: são lidos apenas como candidatos permitidos, mas campos arbitrários nunca são enviados à saída. A inspeção Git lê config para bloquear mecanismos indiretos sem exibir seu conteúdo. Não usar essa ferramenta para autorizar leitura de arquivos de credenciais disfarçados de manifestos.
+
+Exemplo de observação (schema parcial, valor sintético):
+```json
+{"category":"technology","name":"Node.js","value":">=18","classification":"confirmado","basis":"requisito declarado; runtime instalado não verificado","evidence":{"path":"package.json","line":2,"locator":"\"node\""}}
+```
+
+Exit codes: 0 análise concluída no perfil limitado (pode conter desconhecidos e avisos); 1 erro operacional/EACCES/Git necessário indisponível; 2 segurança/limites/Git inválido ou ausente sem flag; 3 argumentos inválidos. Erros não reproduzem conteúdo de configuração.
+
+MANUAL_SQL é a política padrão indicada, não uma substituição de modo previamente escolhido pelo projeto. Discover não lê/reescreve ENVIRONMENT nem verifica aprovações de banco; DB_CHANGE/DB_EXEC e demais portões permanecem obrigatórios. Nenhuma operação de banco ocorre, em qualquer modo.
+
+## Validação e próximos passos
+Etapa 1: fixtures sintéticas multi-stack e segurança, mais toda a regressão existente. Etapa 2: próprio AI Dev Workflow, com revisão conhecida e comparação de snapshots antes/depois. Etapa 3: cópias reais selecionadas e explicitamente autorizadas, ainda pendente; nenhum projeto real/piloto faz parte da autorização atual. Windows/Linux/Docker e reconhecimento real por Codex/Continue permanecem não comprovados. Docker não foi executado nesta task.
+
+G4 autoriza implementar e testar localmente, não G5. Relatório e evidências em tasks/TASK-006_REPORT.md; aprovação G4 e aceite local anterior da TASK-005 em project/DECISIONS.md. O resultado de discover é insumo para um Discovery humano no modelo existente e posterior G1.
+
+## Correções TASK-006.1 — contextos e classificações
+O leitor de diretórios valida os componentes reais da raiz e do caminho relativo; não acrescenta /probe nem consulta filhos fictícios. apps/probe é um módulo legítimo. Traversal, symlinks/junctions, arquivos no lugar de diretórios e redirecionamentos continuam bloqueados; bloqueios de hardlinks nos candidatos permanecem.
+
+package.json confirma somente a presença do manifesto. Node.js sem engines.node é inferido pelo ecossistema, sem afirmar requisito; requisito presente mas fora do subconjunto numérico suportado fica desconhecido. Apenas engines.node suportado é classificado como requisito confirmado. Isso não verifica o runtime instalado.
+
+Compose: confirmar imagem apenas no subconjunto block mapping services na raiz / nome simples de serviço com dois espaços / image com quatro espaços, valor simples conhecido (aspas simples/duplas e comentário final suportados). image em environment/labels/extensões ou blocos literais não é imagem de serviço. Arquivos com tabulação, indentação ímpar, aliases/merges, documentos múltiplos, valores de mapping entre aspas fora do image direto, chaves services/serviço/image duplicadas ou image ambíguo recebem fallback conservador: imagens desconhecidas. Isso inclui Compose válido fora do subconjunto reconhecido; não significa configuração inválida. Serviços em fluxo, nomes/keys não suportados e valores privados/parametrizados são sinalizados sem resolução.
+
+Dockerfile: confirmar somente FROM simples independente, inclusive múltiplos stages, comentário e AS estáticos. Arquivo com marcador de heredoc (mesmo candidato ambíguo), continuação com barra invertida ou diretiva escape torna todas as imagens desconhecidas; não interpretar shell nem tentar reconhecer delimitadores dinamicamente. Portanto FROM dentro de heredoc nunca é confirmado. Sintaxe FROM não suportada e imagens fora da lista também ficam desconhecidas. Algumas imagens reais deixarão de ser confirmadas em arquivos complexos: é um limite explícito de segurança da evidência.
+
+CONTAINER_SYNTAX_UNSUPPORTED e observação container-image/selection desconhecida indicam esse limite; coverage.partial registra o diagnóstico. As imagens reconhecidas têm linha do match efetivo. Presença de Dockerfile/Compose continua confirmada separadamente, sem afirmar execução.
+
+A política Git não mudou. GIT_NESTED é disparado pela presença de marcador .git ancestral; não comprova que esse pai seja repositório válido. No checkout original há esse marcador e a autovalidação integral continua bloqueada. Não remover o marcador nem usar --allow-no-git para contornar; avaliar checkout independente seguro somente em escopo autorizado. Windows/Linux/Docker, clientes e cópias reais permanecem pendentes.
+
+### TASK-006.2 — aliases Dockerfile
+FROM que referencia alias de stage definido anteriormente não gera nova evidência de imagem externa/banco. Aliases são comparados conservadoramente sem distinção de caixa e podem formar cadeias; seus nomes não são exibidos como produtos. Imagem externa com tag (por exemplo mysql:8.0) permanece distinta do alias mysql; uma referência externa anterior à definição do alias também continua sendo evidência. O reconhecimento não executa nem inspeciona conteúdo do stage. Demais limites de heredoc, sintaxe ambígua e GIT_NESTED permanecem.
+
+## Diretório atual (TASK-008)
+`node /caminho/ai-dev-workflow/bin/ai-dev-workflow.js discover --json` usa process.cwd() quando --target não é informado. `discover --allow-no-git --json` mantém a opção explícita exigida para ausência real de Git. --target fornecido prevalece, inclusive caminhos relativos; vazio é erro de argumentos. Não há descoberta automática de raiz nem promoção de subpasta. Todos os bloqueios, limites e a política GIT_NESTED permanecem. CWD_UNAVAILABLE (exit 1) indica que o diretório atual não pôde ser obtido; consulte [a política de alvo](CLI.md#alvo-implícito-task-008).
+
+
+## Salvar o resultado (TASK-009)
+`discover --save` grava relatório atual, snapshot e evento seguro, com preservação de personalizações. Sem save, a análise permanece somente leitura e a sugestão em texto não grava nada; JSON não recebe sugestão. Gravar exige branch de task/Git seguro, ou ausência real de Git com --allow-no-git. Não combina com --dry-run. Consultar [persistência, limites e recuperação](PERSISTENCE.md); análise estática e aprovações humanas mantêm seus limites anteriores.

package/docs/LAYOUT.md

@@ -0,0 +1,13 @@
+# Estrutura instalada e compatibilidade
+
+Primeiras instalações usam template 0.3.0, layout central-v2 e manifesto 2.0.0:
+
+- Núcleo: .ai-dev-workflow/agents, rules, stacks, templates, integrations e docs/WORKFLOW.md.
+- Adaptadores: AGENTS.md, CLAUDE.md, GEMINI.md, .continue/ e .github/pull_request_template.md nos caminhos esperados pelos clientes. Presença de arquivo não comprova carregamento real.
+- Contexto personalizado: docs/project; .gitignore existente é preservado.
+- Controle: .ai-dev-workflow/install.json, install.lock e install-journal.jsonl.
+- Registros opt-in: docs/project/DISCOVERY.md, discovery-history/ e COMMAND_HISTORY.jsonl, com lock/journal próprios e recuperação humana.
+
+Status/doctor/validate leem perfis legados suportados sem migrar o núcleo; init bloqueia migrações incompatíveis. Não mover ou copiar o núcleo manualmente sobre instalação anterior. Hashes comparam bytes, não autenticidade/aprovação. Arquivos personalizados nunca devem ser sobrescritos silenciosamente.
+
+Consulte [CLI](CLI.md), [persistência](PERSISTENCE.md) e [multi-IA](MULTI_AI.md). MANUAL_SQL e aprovações humanas permanecem obrigatórios. Distribuir a ferramenta não atualiza a stack da aplicação.

package/docs/MULTI_AI.md

@@ -0,0 +1,36 @@
+# Suporte multi-IA — TASK-007
+CLI 0.5.0; template 0.3.0; manifesto 2.0.0. Implementação local para G5, sem comprovação de carregamento real pelos clientes.
+
+## Uma fonte de regras
+AGENTS.md e as regras/processo canônicos continuam existentes; nenhum conteúdo normativo é copiado para CLAUDE.md/GEMINI.md. Os novos arquivos contêm apenas imports locais de AGENTS.md, workflow e regras centrais obrigatórias, incluindo banco. Papéis e templates continuam sob .ai-dev-workflow; os contextos do projeto em docs/project são lidos conforme fase e autorização. Não há dependência de fornecedor, chamadas de IA, plugins, perguntas interativas ou configuração global no init.
+
+No checkout da ferramenta, CLAUDE.md/GEMINI.md importam docs/WORKFLOW e rules/ (fontes reais). O builder prepara bytes canônicos para os destinos instalados: imports de .ai-dev-workflow/docs/WORKFLOW e .ai-dev-workflow/rules. Não há transformação durante init. AGENTS.md, .continue e seus payloads anteriores permanecem inalterados.
+
+## Convenções e limites de comprovação
+- Claude Code: CLAUDE.md admite imports @path relativos ao arquivo. A documentação oficial descreve @AGENTS.md como forma de compartilhar instruções. Fonte: https://code.claude.com/docs/en/memory (consultada no planejamento, 2026-11-10).
+- Gemini CLI: GEMINI.md admite imports @./file.md e contexto hierárquico. Fontes: https://geminicli.com/docs/cli/gemini-md/ e https://geminicli.com/docs/reference/memport/ (consultadas no planejamento, 2026-11-10).
+- Codex/Continue: adaptadores anteriores preservados. Não presumir que um cliente herda configuração de outro.
+
+Presença e resolução estática de imports não comprovam que o cliente os carregou ou seguiu. Versão, confiança do workspace, exclusões e configuração do cliente podem alterar o comportamento. Teste real futuro deve registrar versão/configuração, caminhos reconhecidos e contexto carregado em fixture autorizada, sem segredos e respeitando G0 antes de transmitir dados. Não executar clientes, instalar agentes, usar /init de clientes ou configurar permissões globais como parte desta task. As instruções não substituem sandbox/ACLs nem autorizam ferramentas.
+
+## Instalação e personalizações
+O comando continua init --target DIR --track new|existing, com --dry-run/--json opcionais. Somente primeiras instalações recebem os dois arquivos. Existe um único catálogo selecionado por perfil, sem wizard ou escolha obrigatória de IA. CLAUDE.md/GEMINI.md ausentes são criados exclusivamente pelo journal; presentes são preservados byte a byte, inclusive vazios, CRLF e instruções próprias. Não há append, merge, overwrite ou imports acrescentados automaticamente. Arquivos AGENTS/.continue diferentes continuam conflitos gerenciados.
+
+Os dois adaptadores são kind custom, usando a semântica já existente no manifesto. Hash base identifica o conteúdo adotado/criado; status mostra customized se houver alteração posterior. Validate não certifica conteúdo, coerência, presença de imports ou integração de adaptadores personalizados. Na adoção inicial o hash é do arquivo existente: ele pode aparecer unchanged sem conter o workflow. Revise operations/preserve-custom e os arquivos manualmente antes de depender deles; não copiar regras sobre personalizações. Imports do catálogo canônico são conferidos estaticamente. Remoção de um adaptador registrado exige reconciliação, não recriação silenciosa. Symlinks/junctions, hardlinks e tipos inseguros nos novos adaptadores são bloqueados no plano e inspeções.
+
+## Perfis e versões
+| Manifesto/template | Diagnóstico | init |
+| --- | --- | --- |
+| 1.0.0 / 0.1.0, sem layoutVersion | Snapshot legacy-v1, somente leitura | LEGACY_READ_ONLY |
+| 2.0.0 / 0.2.0, central-v2 | Snapshot central anterior, somente leitura | TEMPLATE_READ_ONLY |
+| 2.0.0 / 0.3.0, central-v2 | Perfil atual, 40 fontes + 3 contextos | Primeira instalação/reexecução equivalente |
+| Desconhecido ou inventário inválido | Bloqueio, sem fallback | Nenhuma migração |
+
+Formato 2.0.0 mantido porque campos, tipos, kinds e semântica de hashes não mudaram; templateVersion distingue inventários exatos. Novos adaptadores usam kind custom já suportado. Não usar versão do CLI para reinterpretar inventário antigo. Catálogo anterior em catalog/central-v0.2.json e bytes imutáveis em payload/central-v0.2 mantêm source lógico original do manifesto (payload/central/...), embora o leitor obtenha os bytes do snapshot congelado. O builder não regenera snapshots. Leitores anteriores não são prometidos para o novo template; não há downgrade automático.
+
+A CLI nova inspeciona instalações anteriores sem acrescentar arquivos, migrar, reparar ou sobrescrever manifesto. init anterior é bloqueado inclusive --dry-run. Mesmo o template 0.2.0 completo e íntegro não recebe os adaptadores automaticamente. Atualização futura exige task/plano humano próprio. Instalações atuais equivalentes continuam idempotentes; dry-run não cria diretórios, journal, lock ou manifesto.
+
+## Segurança e validação
+MANUAL_SQL e G0–G6/DB_CHANGE/DB_EXEC continuam canônicos; instalar/importar arquivos não concede aprovações. Git/paths, lock, journal, recuperação humana e create exclusivo preservados. Journal pendente bloqueia todos os perfis. Sem migração, banco, execução de cliente, rede de IA, atualização de stack ou dependências.
+
+Testes locais devem incluir os 244 cenários anteriores, fixtures das duas trilhas, novos adaptadores ausentes/personalizados/perdidos, três perfis, imports inválidos, ENOSPC, links/hardlinks e pacote extraído. Relatório em tasks/TASK-007_REPORT.md. Carregamento real Codex/Continue/Claude Code/Gemini CLI, Windows/Linux/Docker e projetos reais permanecem pendentes. GIT_NESTED no checkout original não é removido nem contornado para testar clientes.

package/docs/PERSISTENCE.md

@@ -0,0 +1,80 @@
+# Persistência opt-in — TASK-009
+
+## Autorizar a gravação
+
+Sem `--save`, doctor, discover, status e validate continuam somente leitura. Init mantém seu contrato de instalação. Depois de discover bem-sucedido em texto, a CLI sugere discretamente `discover --save`, mantendo o mesmo destino; JSON e códigos de saída não recebem a sugestão. Nada é salvo por essa sugestão.
+
+`--save` autoriza criar registros locais no destino canonicalizado, informado também em stderr antes da operação. Confira o destino, principalmente ao omitir `--target` (usa cwd, sem subir diretórios). A opção não concede aprovação G1/G5, DB_CHANGE ou DB_EXEC. MANUAL_SQL e os controles de produção permanecem intactos.
+
+Todas as gravações exigem Git seguro e branch de task, inclusive em status/validate/discover. Discover sem save continua aceitando qualquer branch ou HEAD destacado; não confundir leitura com autorização de gravação. A única exceção é `discover --allow-no-git --save`, permitida em diretório realmente sem Git local nem marcador Git ancestral. Git inseguro nunca tem fallback. O save exige o executável Git nas instalações Git, inclusive em status/validate; sem save esses dois comandos não passam a executá-lo. Não há git init ou migração implícita.
+
+Exemplos com Node.js 24 exclusivo da ferramenta (substituir placeholders):
+
+```sh
+node "/caminho/ai-dev-workflow/bin/ai-dev-workflow.js" init --target "/caminho/projeto" --track existing --save --json
+node "/caminho/ai-dev-workflow/bin/ai-dev-workflow.js" discover --target "/caminho/projeto" --save --json
+node "/caminho/ai-dev-workflow/bin/ai-dev-workflow.js" doctor --target "/caminho/projeto" --save
+node "/caminho/ai-dev-workflow/bin/ai-dev-workflow.js" status --target "/caminho/projeto" --save
+node "/caminho/ai-dev-workflow/bin/ai-dev-workflow.js" validate --target "/caminho/projeto" --save --json
+node "/caminho/ai-dev-workflow/bin/ai-dev-workflow.js" discover --target "/caminho/sem-git" --allow-no-git --save
+```
+
+No PowerShell, usar os mesmos argumentos com caminhos Windows entre aspas. A portabilidade desta camada ainda depende de execução real nas outras plataformas. Nenhum Docker ou cliente de IA foi executado para validá-la.
+
+`--save --dry-run` é erro de argumentos (3), antes de qualquer escrita, inclusive combinado com help. Help/version isolados não geram eventos. `--json` mantém um único objeto em stdout; stderr pode conter o aviso de destino. Flags `readOnly` dos diagnósticos descrevem a inspeção, não a persistência explicitamente solicitada; consulte `persistence.wrote`.
+
+## Arquivos e preservação
+
+| Caminho no projeto | Política |
+| --- | --- |
+| docs/project/DISCOVERY.md | Relatório corrente; criado se ausente. Só atualizado quando seus bytes correspondem ao último snapshot identificado pelo histórico válido. |
+| docs/project/discovery-history/UUID.md | Nova versão por discover salvo com sucesso; criação exclusiva, sem apagar versões anteriores. |
+| docs/project/COMMAND_HISTORY.jsonl | Eventos estruturados de todos os cinco comandos com save; append-only lógico, sem truncamento ou rotação automática. |
+| docs/project/.command-history.lock | Exclusão mútua para gravadores; lock restante exige revisão humana. |
+| docs/project/.command-history-journal.json | Intenção/hashes antes da publicação; presença, mesmo vazia, bloqueia novos saves. |
+
+Discovery preexistente, inclusive vazio, ou editado manualmente é preservado byte a byte (`current: preserved-custom`). A nova versão é salva no histórico para consulta manual. A CLI não importa decisões de aprovação do relatório, não faz merge e não adota arquivo personalizado como sua versão gerenciada. Se o último snapshot referenciado estiver ausente/adulterado, o save de Discovery bloqueia com HISTORY_INVALID. Os demais comandos salvam somente eventos, sem atualizar Discovery ou certificar seus snapshots.
+
+Os registros são documentos do projeto, fora do inventário instalado: não alteram formatos de catálogo/manifesto/journal de instalação. O save explícito em instalação legada permite esses documentos; o núcleo continua sem migração e init permanece bloqueado. Hashes são comparação de bytes, não autenticação ou prova de autoria.
+
+## Dados seguros e consulta
+
+O Markdown usa uma projeção limitada das observações: tecnologias conhecidas, versões numéricas suportadas, classificações confirmado/inferido/desconhecido, caminhos relativos/linhas e limitações fixas. Não é uma cópia do JSON bruto. Formatos não reconhecidos não são resolvidos. Declarado não significa instalado, nem banco configurado significa banco ativo. Revisão humana/G1 continuam necessárias.
+
+A ordem das linhas no JSONL é a ordem de registro sob o lock de persistência, não necessariamente a ordem de início ou conclusão dos comandos. O timestamp UTC é capturado sob esse lock, ao preparar o evento e o relatório, antes do journal/publicação. Não é uma medição do tempo de execução nem prova do instante exato de conclusão. O relógio do sistema pode regredir ou repetir valores: timestamps não têm ordenação absoluta garantida. Consultas devem preservar a ordem das linhas; não reordenar o histórico por data ou UUID.
+
+Cada linha JSONL contém historyVersion, UUID, timestamp UTC, cliVersion, comando, resultado, operationExitCode e summaryCode fixo; discover concluído acrescenta snapshot relativo, sha256 e política do documento corrente. Não são registrados argumentos, alvo absoluto, saída bruta, stack traces, conteúdos personalizados, credenciais ou mensagens arbitrárias de erro.
+
+Exemplo ilustrativo de evento (não uma evidência de execução):
+
+```json
+{"historyVersion":"1.0.0","id":"00000000-0000-4000-8000-000000000001","timestamp":"2026-11-11T12:00:00.000Z","cliVersion":"0.4.0","command":"status","result":"completed","operationExitCode":0,"summaryCode":"COMPLETED"}
+```
+
+Consultar o arquivo JSONL no editor e os snapshots Markdown diretamente. Não há novo comando de consulta, serviço, banco, telemetria ou exportação automática. O histórico é parcial: invocações sem save, argumentos inválidos, falhas anteriores à validação segura do alvo, falhas de preflight, help/version e processos interrompidos antes do evento não ficam registrados. Um comando pode ter sido executado sem haver evento concluído. O histórico não é trilha forense inviolável e pode ser editado externamente; JSONL inválido bloqueia novos saves sem reparo automático. Git/.gitignore não asseguram ausência de dados sensíveis; revisar artefatos antes de versionar.
+
+## Resultado, falhas e recuperação
+
+Exit codes existentes são preservados: 0 concluído, 1 operacional, 2 bloqueio/conflito, 3 argumentos inválidos. Com save, `operationExitCode` informa o resultado do comando. `persistence.ok` informa a gravação. Falha de gravação torna o resultado final não aprovado e retorna 1 ou 2 conforme a falha; a operação pode já ter concluído. Por exemplo, init pode instalar com sucesso e falhar ao salvar o evento. Não repetir init automaticamente.
+
+Falha de persistência retorna `writeState: incomplete-or-unknown`, sem alegar ausência de escrita; pode haver arquivos já publicados, temporários `.record-UUID-N.tmp` ou evento já consolidado. Preflight bloqueado não inclui necessariamente esses campos.
+
+O journal de persistência é independente de `.ai-dev-workflow/install-journal.jsonl`. Não removê-los para contornar falhas. Na presença de lock/journal, ENOSPC ou interrupção:
+
+1. Pare os gravadores e confirme alvo, permissões, espaço e ausência de outro processo ativo.
+2. Preserve cópias locais seguras dos arquivos envolvidos, journal, lock e temporários; não divulgar conteúdo personalizado.
+3. Com revisão humana, compare caminhos e hashes planejados com histórico, corrente e snapshots. Um arquivo parcial nunca deve ser adotado como relatório válido. Verifique separadamente o estado da instalação se o comando foi init.
+4. Defina recuperação/rollback manual específico e obtenha autorização antes de alterar arquivos existentes ou retirar marcadores. Não existe repair, replay, resume, force ou limpeza automática. Uma nova execução não faz reconciliação.
+5. Revalide antes de solicitar outro save. Comandos sem save mantêm seus contratos, sujeitos ao journal de instalação e segurança anteriores; journal exclusivo de persistência não é automaticamente removido por eles.
+
+## Segurança, atomicidade e limites
+
+Reutiliza validação de alvo/Git/GIT_NESTED e recusa links, hardlinks preexistentes, arquivos especiais e traversal nos caminhos de persistência. Leituras limitadas verificam identidade/tamanho do arquivo. Criação é exclusiva; substituição do corrente reconhecido e atualização do histórico conferem o hash anterior. Lock exclusivo protege gravadores cooperantes.
+
+Antes das publicações, grava e sincroniza journal com plano/hashes. Cada arquivo usa temporário sincronizado e publicação atômica: rename ao substituir arquivo reconhecido; link exclusivo seguido de unlink do temporário ao criar um arquivo sem sobrescrita. Esse hardlink transitório é criado pela própria ferramenta e termina com um único nome; interrupção nessa janela bloqueia a recuperação em vez de aceitar links restantes. O histórico mantém integralmente o prefixo anterior, mas seu append é implementado por cópia+rename, não escrita parcial no arquivo corrente.
+
+Limites em bytes: relatório 2 MiB; evento 16 KiB; histórico total 8 MiB. Schema/UTF-8/IDs únicos/referências são validados; histórico truncado/inválido bloqueia. Sem compactação, rotação, reparo ou remoção automática. Relatório também limita a projeção a 10000 observações.
+
+Atomicidade é por arquivo, não transação multifarquivo. Diretórios criados antes do journal podem permanecer após falha. Exigir filesystem local estável com exclusividade, hardlink/rename e fsync de diretórios confiáveis; falta dessas capacidades falha conservadoramente, sem promessa de portabilidade universal. Persistência contra queda de energia e filesystem hostil não foi comprovada. ACLs devem impedir troca concorrente de caminhos, mounts ou conteúdo por processo hostil; a CLI não oferece operações openat completas nem segurança absoluta contra TOCTOU. Locks não provam identidade humana ou integridade da origem.
+
+Testes sintéticos locais não comprovam Windows/Linux/Docker, clientes reais ou projetos reais. Testes futuros em projetos reais dependem de cópias isoladas selecionadas e autorização humana específica.

package/docs/QUICKSTART.md

@@ -0,0 +1,203 @@
+# Começar com a CLI do AI Dev Workflow
+
+A CLI instala instruções e prepara o contexto do workflow em projetos novos ou existentes, independentemente da stack. CLI **0.5.0**, template central **0.3.0**. Não cria a aplicação, não realiza o Discovery humano completo automaticamente, não executa agentes nem concede aprovações humanas.
+
+Este guia usa um checkout local confiável da ferramenta. Primeiras instalações usam .ai-dev-workflow para o núcleo e preservam docs/project para documentos próprios. Se já houver manifesto legado, init é bloqueado (LEGACY_READ_ONLY): use doctor/status/validate somente leitura; não há migração automática. Não há pacote npm publicado. Para detalhes e recuperação, consulte o [guia da CLI](CLI.md).
+
+## 1. Conferir os pré-requisitos
+
+- Node.js **24.x** disponível exclusivamente para executar a ferramenta, ou Docker Engine/Desktop previamente instalado.
+- Git **2.28+** para init/doctor; na alternativa Docker, Git já pertence à imagem. Status/validate não executam Git, mas exigem metadados locais verificáveis.
+- Destino autorizado, existente, com `.git` local, na raiz do repositório e em branch de task para init/doctor. Não usar subpastas da aplicação como alvo.
+- Permissão para ler os arquivos e, ao instalar, criar os arquivos planejados. Nenhuma dependência npm é necessária.
+
+Não troque o runtime da aplicação. Não execute npm install/update, nem altere package.json, lockfiles, PATH ou gerenciadores de versões do projeto para usar esta CLI. Escolha um executável Node 24 separado ou Docker. Não é necessário chmod +x ao executar explicitamente via node.
+
+Os caminhos `/caminho/...` abaixo são placeholders: substitua-os por caminhos absolutos reais. `node` deve ser o executável 24 da ferramenta; se necessário, use seu caminho absoluto.
+
+## 2. Preparar o destino
+
+### Projeto novo
+
+Após autorização para criar o diretório e os metadados Git, escolha um local sem repositório Git pai e prepare manualmente:
+
+```sh
+mkdir "/caminho/projeto-novo"
+git init --initial-branch=feature/TASK-001-bootstrap "/caminho/projeto-novo"
+```
+
+Confira a raiz e a branch mesmo antes do primeiro commit (branch unborn):
+
+```sh
+git -C "/caminho/projeto-novo" rev-parse --show-toplevel
+git -C "/caminho/projeto-novo" symbolic-ref --short HEAD
+```
+
+Esses comandos não dependem de um commit existente; symbolic-ref deve indicar feature/TASK-001-bootstrap. Não use rev-parse HEAD como requisito de preparação: numa branch unborn ele não resolve um commit.
+
+A CLI não executa esses passos por você. Não é necessário criar commit. A trilha `new` prepara o contexto para **P00 Requirements & Architecture**; o esqueleto da aplicação depende do planejamento e dos portões do workflow.
+
+### Projeto existente
+
+Confirme a raiz e a branch, sem alterar o projeto:
+
+```sh
+git -C "/caminho/projeto" rev-parse --show-toplevel
+git -C "/caminho/projeto" symbolic-ref --short HEAD
+git -C "/caminho/projeto" status --short --branch
+```
+
+Use a raiz retornada como --target. Se ainda não houver Git ou branch de task, interrompa e combine a preparação manual com o responsável; não inicialize Git em um diretório pai por conveniência. Main/master e HEAD destacado bloqueiam init/doctor. A trilha `existing` prepara **P01 Discovery**, que deverá ser realizado posteriormente pelo agente/humano com evidências reais.
+
+Nos dois casos, worktrees/submódulos com metadados externos, repositórios aninhados e mecanismos indiretos não suportados são bloqueados em init/doctor. Links/junctions no destino ou ancestrais são recusados, salvo aliases de sistema macOS estritamente verificados. Em `.git`, links inclusive internos, hardlinks, arquivos especiais, alternates, promisor/partial clone, reftable e certas configurações indiretas são bloqueados nos quatro comandos. Não remova controles para contornar erros: veja a [política completa de isolamento](CLI.md#armazenamento-git-suportado-e-bloqueado).
+
+## 3. Planejar com Node.js 24 (macOS/Linux)
+
+Confira a interface e a versão:
+
+```sh
+node "/caminho/ai-dev-workflow/bin/ai-dev-workflow.js" --help
+node "/caminho/ai-dev-workflow/bin/ai-dev-workflow.js" --version --json
+```
+
+Escolha **um** dos planos conforme a trilha:
+
+```sh
+node "/caminho/ai-dev-workflow/bin/ai-dev-workflow.js" init --target "/caminho/projeto-novo" --track new --dry-run --json
+node "/caminho/ai-dev-workflow/bin/ai-dev-workflow.js" init --target "/caminho/projeto" --track existing --dry-run --json
+```
+
+`--dry-run` em init calcula o plano sem criar arquivos, diretórios, lock, journal ou manifesto. Não contorna conflitos nem instalação interrompida. Revise canonicalTarget e operations antes de autorizar a instalação. Arquivos diferentes não são sobrescritos automaticamente; conflitos gerenciados bloqueiam o plano inteiro. Contextos preexistentes válidos são preservados como personalizados. O .gitignore existente também é preservado integralmente, sem acrescentar regras; se ausente na primeira instalação, o plano propõe criar o modelo. Revise as regras de versionamento locais; a CLI não certifica sua segurança. Veja a política no guia da CLI.
+
+## 4. Instalar e conferir
+
+Após autorização para criar os arquivos no destino revisado, execute a trilha escolhida sem --dry-run. Exemplo para projeto existente:
+
+```sh
+node "/caminho/ai-dev-workflow/bin/ai-dev-workflow.js" init --target "/caminho/projeto" --track existing --json
+node "/caminho/ai-dev-workflow/bin/ai-dev-workflow.js" doctor --target "/caminho/projeto" --json
+node "/caminho/ai-dev-workflow/bin/ai-dev-workflow.js" status --target "/caminho/projeto" --json
+node "/caminho/ai-dev-workflow/bin/ai-dev-workflow.js" validate --target "/caminho/projeto" --json
+```
+
+Para projeto novo, use `--track new` em init e o mesmo destino novo nos quatro comandos. `--track` só é aceito em init; não permite mudar implicitamente a trilha já instalada.
+
+| Comando | O que conferir |
+| --- | --- |
+| init | Plano/criações, conflitos, contexto inicial e manifesto |
+| doctor | Isolamento Git, raiz/branch/HEAD e validação da instalação; não repara |
+| status | Versões, trilha e arquivos unchanged/modified/customized/missing; não interpreta aprovações |
+| validate | Hashes, inventário, referências, frontmatter básico, modo declarado e ausência de journal pendente |
+
+Sem --save, as três inspeções são somente leitura; também aceitam --dry-run, sem transformar o diagnóstico em simulação de reparo. Instalar novamente um estado equivalente não regrava arquivos persistentes; init ainda adquire/libera lock efêmero.
+
+`--json` envia um único objeto JSON para stdout. Init sem --dry-run anuncia o destino canonicalizado em stderr antes das escritas; capture os dois canais separadamente. Exemplo real de versão:
+
+```json
+{"ok":true,"message":"0.5.0"}
+```
+
+Os resultados variam por comando: init inclui operations; doctor, checks; status, files; validate, findings. `ok:true` não significa aprovação humana ou aplicação testada.
+
+| Código de saída | Interpretação |
+| --- | --- |
+| 0 | Operação concluída; status pode apresentar drift sem falhar |
+| 1 | Falha operacional: I/O/permissões, Node incompatível ou executável Git necessário indisponível |
+| 2 | Conflito ou validação bloqueante: metadados inseguros, journal, manifesto inválido, arquivo conflitante ou lock ocupado |
+| 3 | Argumentos inválidos, como comando/flag desconhecidos ou --target vazio ou ausência de --track obrigatório no init |
+
+## 5. Alternativa Docker
+
+Docker isola o runtime da ferramenta. **Não replica automaticamente a aplicação ou qualquer produção**, nem precisa iniciar os serviços dela. A imagem deve ser preparada a partir do checkout atual da ferramenta: uma imagem antiga pode conter código anterior às correções.
+
+Após autorização para preparar a imagem local:
+
+```sh
+docker build --pull=false -t ai-dev-workflow:local "/caminho/ai-dev-workflow"
+```
+
+O build pode acessar a base e repositórios Debian para instalar Git somente na imagem. A execução abaixo usa rede desabilitada; não instala nada no host ou projeto. Planeje montando apenas a raiz autorizada, somente leitura:
+
+```sh
+docker run --rm --network none --read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privileges --mount "type=bind,source=/caminho/projeto,target=/project,readonly" ai-dev-workflow:local init --target /project --track existing --dry-run --json
+```
+
+Depois da autorização da criação, permita escrita somente nesse mount e retire --dry-run:
+
+```sh
+docker run --rm --network none --read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privileges --mount "type=bind,source=/caminho/projeto,target=/project" ai-dev-workflow:local init --target /project --track existing --json
+```
+
+Para inspecionar, volte ao mount somente leitura:
+
+```sh
+docker run --rm --network none --read-only --tmpfs /tmp --mount "type=bind,source=/caminho/projeto,target=/project,readonly" ai-dev-workflow:local doctor --target /project --json
+docker run --rm --network none --read-only --tmpfs /tmp --mount "type=bind,source=/caminho/projeto,target=/project,readonly" ai-dev-workflow:local status --target /project --json
+docker run --rm --network none --read-only --tmpfs /tmp --mount "type=bind,source=/caminho/projeto,target=/project,readonly" ai-dev-workflow:local validate --target /project --json
+```
+
+A imagem usa USER node. No Linux, UID/GID e propriedade devem ser compatíveis; no Docker Desktop macOS/Windows, confira compartilhamento de pastas e conversão dos caminhos. Não configure safe.directory=* nem use root/chmod geral para contornar erros. Não monte socket Docker, diretório pessoal ou produção. O [guia completo](CLI.md#docker-sem-nodegit-no-host) detalha permissões e limitações.
+
+## 6. Windows PowerShell
+
+Use Node 24 separado da aplicação. Confira raiz/branch e planeje antes de instalar:
+
+```powershell
+git -C "C:\projetos\legado" rev-parse --show-toplevel
+git -C "C:\projetos\legado" symbolic-ref --short HEAD
+node "C:\ferramentas\ai-dev-workflow\bin\ai-dev-workflow.js" init --target "C:\projetos\legado" --track existing --dry-run --json
+```
+
+Após revisar o plano e autorizar a criação no projeto existente:
+
+```powershell
+node "C:\ferramentas\ai-dev-workflow\bin\ai-dev-workflow.js" init --target "C:\projetos\legado" --track existing --json
+node "C:\ferramentas\ai-dev-workflow\bin\ai-dev-workflow.js" doctor --target "C:\projetos\legado" --json
+node "C:\ferramentas\ai-dev-workflow\bin\ai-dev-workflow.js" status --target "C:\projetos\legado" --json
+node "C:\ferramentas\ai-dev-workflow\bin\ai-dev-workflow.js" validate --target "C:\projetos\legado" --json
+```
+
+Para projeto novo, prepare diretório/Git somente após autorização conforme a seção 2, usando caminhos Windows, e selecione --track new. symbolic-ref também funciona em branches unborn no PowerShell.
+
+Nos exemplos Docker, adapte source em --mount ao caminho Windows compartilhado. Execução Linux em Docker não comprova funcionamento nativo Windows/macOS.
+
+## Problemas comuns
+
+| Sintoma | Procedimento seguro |
+| --- | --- |
+| NODE_VERSION / GIT_REQUIRED | Usar runtime/executável da ferramenta já preparado ou Docker; não atualizar a stack da aplicação |
+| TARGET_MISSING / GIT_MISSING | Confirmar o destino; preparar diretório/Git manualmente somente após autorização |
+| GIT_PARENT / GIT_NESTED / GIT_PROTECTED / GIT_DETACHED | Usar a raiz autorizada em branch adequada; pedir revisão da preparação, sem bypass |
+| UNSAFE_TARGET / GIT_EXTERNAL_METADATA | Conferir caminhos reais e limites; pedir revisão humana de uma cópia independente suportada, sem apagar metadados |
+| GIT_METADATA_LIMIT | A árvore .git excedeu 100000 entradas ou 64 níveis; interromper e pedir revisão humana. Não apontar --target para uma subpasta nem apagar objetos/logs para contornar o limite |
+| LEGACY_READ_ONLY | Instalação antiga aceita apenas inspeções doctor/status/validate; não mover arquivos nem editar manifesto para simular atualização |
+| NAMESPACE_CONFLICT | Preservar .ai-dev-workflow desconhecido e solicitar reconciliação humana; não apagar o diretório |
+| CONFLICT / arquivo modified | Comparar diferenças e preservar personalizações; não existe --force ou merge automático |
+| INSTALL_INCOMPLETE / INSTALL_LOCKED | Parar, confirmar se há instalador ativo e preservar evidências; não apagar journal/lock às cegas |
+| CONTEXT_REVIEW_REQUIRED | Revisar ENVIRONMENT e declarar modo aprovado explicitamente; não substituir contexto por defaults |
+| I/O, ENOSPC ou propriedade Git duvidosa | Interromper, preservar artefatos e revisar espaço/permissões/propriedade; não repetir init como reparo |
+
+Para instalação interrompida, siga a [reconciliação humana](CLI.md#instalação-interrompida-e-reconciliação-humana). Não há repair/resume, upgrade ou downgrade automático.
+
+## Próximos passos
+
+No checkout, consulte [AGENTS.md](../AGENTS.md) e o [workflow](WORKFLOW.md). No projeto instalado central, leia AGENTS.md, .ai-dev-workflow/docs/WORKFLOW.md e as regras em .ai-dev-workflow/rules; os links deste guia apontam para as fontes do checkout. Confira docs/project/CURRENT_STATE.md, ENVIRONMENT.md e DECISIONS.md no destino: novos contextos registram stack/ambiente não verificados e aprovações pendentes. Execute P00 para new ou P01 para existing, produza evidências e obtenha os portões humanos antes de avançar. A CLI não realiza o Discovery humano completo, testes funcionais da aplicação ou aprovações por você.
+
+**MANUAL_SQL é o padrão.** O agente apenas prepara SQL e instruções para execução humana; aprovação da task ou G4/G5/G6 não concede execução de banco. Escolha de outro modo não substitui G2, DB_CHANGE e DB_EXEC específicos; produção exige também G6 e controles adicionais. Consulte as [regras de banco](../rules/database.md). Nenhum comando da CLI executa SQL, migrations ou seeders.
+
+## Discovery estático opcional
+
+A CLI 0.3.0 oferece `discover --target DIR --json` como inventário técnico limitado, sem escrever relatórios ou realizar o Discovery humano completo. Não aprova G1. Destino sem Git exige `--allow-no-git`; veja [política e cobertura](DISCOVERY_CLI.md). As orientações de preparação Git acima continuam necessárias para instalar com init.
+
+## Adaptadores multi-IA
+
+CLI 0.4.0/template 0.3.0 acrescentam CLAUDE.md/GEMINI.md com imports locais, preservando arquivos personalizados. Templates anteriores são apenas inspecionados: init retorna LEGACY_READ_ONLY ou TEMPLATE_READ_ONLY, sem atualização automática. Veja [o guia multi-IA](MULTI_AI.md); arquivos presentes não comprovam carregamento por clientes.
+
+## Comandos na pasta atual (TASK-008)
+Após confirmar que o terminal está na raiz autorizada do projeto, --target pode ser omitido em init, doctor, status, validate e discover. Exemplo: `node /caminho/ai-dev-workflow/bin/ai-dev-workflow.js doctor --json`. init continua exigindo --track, por exemplo `init --track existing --dry-run --json`; sem Git, discover continua exigindo --allow-no-git. Exemplos anteriores com --target explícito permanecem válidos e prevalecem sobre a pasta atual. Não há busca de raiz Git ou fallback para o pai; subpastas e GIT_NESTED mantêm seus bloqueios. Revise canonicalTarget antes de instalar. No PowerShell, use o caminho absoluto Windows do executável entre aspas com os mesmos argumentos. Veja [o contrato completo](CLI.md#alvo-implícito-task-008).
+
+
+## Guardar diagnósticos e consultar registros
+Após revisar o alvo e autorizar a gravação, use `node "/caminho/ai-dev-workflow/bin/ai-dev-workflow.js" discover --target "/caminho/projeto" --save --json`. Em branch de task segura, salva docs/project/DISCOVERY.md (preservando personalizações), versões em discovery-history/ e evento em COMMAND_HISTORY.jsonl. Init/doctor/status/validate também aceitam --save para eventos. Consulte esses arquivos no editor.
+
+Sem --save, inspeções continuam somente leitura; discover em texto sugere salvar. --save --dry-run é rejeitado sem escrita. Save exige Git seguro/branch de task (ou discover --allow-no-git em ausência real de Git). Se houver journal/lock ou falha, preserve evidências e não repita init automaticamente: veja [recuperação e limites](PERSISTENCE.md). O histórico é parcial e não concede aprovação humana nem execução de banco.

package/docs/WORKFLOW.md

@@ -0,0 +1,58 @@
+# Workflow e critérios de transição
+
+## Trilhas
+**Existente:** P01 Discovery → G1 → P02 Environment → G2 → P03 Baseline → G3 → P04 Planning → G4 → P05 Development → P06 Validation → G5 → P07 Delivery → G6 (produção quando aplicável).
+
+**Novo:** P00 Requirements & Architecture → G1 → P02 Environment → G2 → P03 Baseline de pré-implementação → G3 → P04 Planning → G4 → P05 Development → P06 Validation → G5 → P07 Delivery → G6.
+
+O G0 (autorização de compartilhamento de código/dados com terceiros) vem **antes** de qualquer integração externa. Pode-se trabalhar inteiramente local sem compartilhar dados.
+
+| Fase | Responsável (papel) | Saída verificável | Próximo passo requer |
+| --- | --- | --- | --- |
+| P00 Requirements (novo) | architect | escopo, requisitos, decisões | G1 |
+| P01 Discovery (existente) | discovery | DISCOVERY preenchido; stack confirmada | G1 |
+| P02 Environment | environment | ENVIRONMENT + instruções reproduzíveis | G2 |
+| P03 Baseline | reviewer | BASELINE com smoke/testes e lacunas; pré-implementação se novo sem aplicação | G3 |
+| P04 Planning | architect | task + critérios de aceitação/rollback | G4 |
+| P05 Development | developer | diff mínimo, sem deploy | P06 |
+| P06 Validation | reviewer | relatório de testes e revisão independente | G5 |
+| P07 Delivery | documentation | docs, PR e release checklist | G6 se houver deploy |
+
+## Bootstrap de projeto novo
+P00 produz REQUIREMENTS e ARCHITECTURE com stack aprovada em G1. P02 aceita esses documentos no lugar de Discovery e prepara o ambiente; G2 aprova sua configuração, sem autorizar banco.
+
+Em P03, antes de existir aplicação, o reviewer registra baseline de pré-implementação: inventário real, ferramentas verificadas, verificações possíveis sem aplicação e testes indisponíveis. G3 aprova esse ponto de partida e suas lacunas, sem declarar funcionalidades aprovadas.
+
+Em P04, o architect cria uma task de bootstrap com arquivos, comandos, versões, critérios e testes. Somente após G4 o developer cria o esqueleto em P05. P06 verifica o bootstrap, registra resultados e acrescenta baseline executável preservando a referência anterior. Depois de G5, tasks funcionais usam essa baseline. Nenhum scaffold ou instalação que o gere pode antecipar G4; instalação de ferramentas em P02 deve estar no escopo aprovado de G1. Banco segue os controles próprios abaixo.
+
+## Como registrar aprovação humana
+`docs/project/DECISIONS.md` é a fonte canônica. Tasks, relatórios e CURRENT_STATE referenciam seus IDs; não duplicam decisões como fontes independentes. Antes da primeira task, registrar no mesmo arquivo as decisões do projeto. Evidência de autorização explícita na conversa pode ser transcrita de forma sanitizada; o agente registra, mas não se autoaprova.
+
+Cada registro contém ID, portão/tipo (G0–G6, DB_MODE, DB_CHANGE, DB_EXEC), estado, data, responsável humano, referência da manifestação, ação, escopo, ambiente/alvo, executor e artefato/revisão aprovada (commit, hash ou revisão documental identificável), restrições e validade.
+
+Estados: **pendente**, **aprovado**, **rejeitado**, **revogado**, **revalidação pendente**. Ausência de resposta não autoriza nada. Rejeição bloqueia a ação; revogação suspende autorização futura. Mudança relevante em escopo, alvo, modo, comandos, riscos ou artefato aprovado exige revalidação humana antes de prosseguir; alterações após G5 retornam à revisão quando afetarem o conteúdo validado. Preservar o histórico acrescentando registros que referenciem o ID anterior. Nova aprovação após rejeição/revogação não apaga o histórico.
+
+## Controle de execução de banco
+`rules/database.md` é obrigatório sempre que houver banco, inclusive bootstrap, testes, seeds e scripts indiretos. Modo padrão por projeto e task: **MANUAL_SQL**; alternativas **AUTOMATIC_LOCAL** e **PRODUCTION_CONTROLLED** dependem de escolha humana registrada. G2 aprova ambiente; DB_CHANGE aprova a mudança; DB_EXEC autoriza a execução concreta. G4 não autoriza escrita. Produção exige ainda G6, backup validado, plano de execução, validação e rollback. Em MANUAL_SQL entregar SQL e roteiro de phpMyAdmin conforme `templates/DATABASE_CHANGE.md`, sem executar alterações.
+
+## Matriz de leitura obrigatória
+Antes de atuar, carregar AGENTS, este workflow, papel da fase, contexto e task existentes. Não presumir carregamento automático por citar caminhos. Todas as fases leem `rules/general.md`, `rules/security.md`, `rules/git-workflow.md` e `rules/cost-control.md`.
+
+| Fase | Papel | Regras adicionais obrigatórias | Artefatos de referência |
+| --- | --- | --- | --- |
+| P00 | architect | database se houver dados persistidos | REQUIREMENTS, ARCHITECTURE, DECISIONS |
+| P01 | discovery | database se houver banco | DISCOVERY, DECISIONS |
+| P02 | environment | testing; database se houver banco | ENVIRONMENT, DECISIONS |
+| P03 | reviewer | testing; database se houver banco | BASELINE, DECISIONS |
+| P04 | architect | testing; database se houver banco | TASK, DATABASE_CHANGE quando aplicável |
+| P05 | developer | testing; database se houver banco | TASK, TASK_REPORT |
+| P06 | reviewer | testing; database se houver banco | TASK, TASK_REPORT, BASELINE |
+| P07 | documentation | testing; database se houver banco | TASK_REPORT, PR_CHECKLIST, CURRENT_STATE |
+
+Os nomes de regras adicionais correspondem a `rules/<nome>.md`; os artefatos são modelos de `templates/`. Aplicar `stacks/*.md` somente após confirmar stack. Se a presença de banco for desconhecida, carregar database preventivamente. A matriz obriga leitura, não concede execução.
+
+## Regras de paradas
+Interrompa se identificar: credenciais expostas, produção confundida com local, dados reais em testes, incompatibilidade crítica, falha de integridade, comportamento inesperado no baseline, instruções contraditórias, custo não autorizado ou necessidade de ação destrutiva.
+
+## Saída mínima por fase
+Evidências observadas, comandos executados, falhas, riscos, decisão pendente e o que *não* foi verificado. Nunca afirmar que algo está funcional só por haver arquivos.

package/integrations/codex/README.md

@@ -0,0 +1,14 @@
+# Codex
+
+O arquivo `AGENTS.md` na raiz é a entrada das regras do agente. Referencie explicitamente as demais regras, templates e arquivos de contexto nos pedidos; verifique o comportamento da sua instalação do Codex. Abra uma fase por vez. Sugestão de primeiro pedido:
+
+> Leia AGENTS.md, docs/WORKFLOW.md e docs/project/CURRENT_STATE.md (se existir). Estamos na fase P01 Discovery de projeto existente. Trabalhe somente leitura, gere diagnóstico no modelo templates/DISCOVERY.md, sem executar comandos que mudam estado. Apresente evidências e solicite aprovação G1.
+
+Mantenha operações destrutivas, Git push/merge e deploy sob confirmação humana e controle de permissões.
+
+Antes de atuar, carregue a matriz em `docs/WORKFLOW.md` e confira isolamento conforme `rules/git-workflow.md`. Registre aprovações somente em DECISIONS, referenciando IDs. Para banco, aplique `rules/database.md`: MANUAL_SQL padrão; G4 não autoriza execução. Não executar migrations/seeders/escrita sem modo permitido e DB_EXEC específico. Essas regras não substituem permissões técnicas.
+
+## Produção e SQL
+Produção permanece bloqueada por padrão. Operações de produção exigem as autorizações humanas específicas do workflow, incluindo G6 para a ação e o ambiente concretos. Operações de banco exigem também G2, DB_CHANGE e DB_EXEC aplicáveis, com executor, alvo e revisão dos scripts identificados; produção exige backup validado, plano de execução, validação e rollback. G4, G5 ou G6 não implicam autorização automática para executar SQL.
+
+MANUAL_SQL permanece como modo padrão: o agente apenas prepara os arquivos SQL e as instruções; a execução é responsabilidade humana, sujeita às autorizações aplicáveis. Nenhuma ferramenta deve executar comandos de escrita no banco sem autorização explícita para a operação e o ambiente. Para execução pelo agente, exigir também modo permitido escolhido pelo humano conforme `rules/database.md`; DB_EXEC humano não autoriza execução pelo agente. Essas instruções não substituem permissões técnicas.

package/integrations/continue/README.md

@@ -0,0 +1,19 @@
+# Continue
+
+A pasta `.continue/rules/` contém regras e `.continue/prompts/` contém comandos reutilizáveis. A sintaxe e interface podem mudar entre versões; valide que o Continue reconhece cada arquivo antes de depender dele. O modelo precisa oferecer suporte às funcionalidades desejadas (ferramentas/edit/agent).
+
+1. Abra o projeto no VS Code.
+2. Confira se os prompts aparecem ao digitar `/`.
+3. Em projetos sensíveis prefira Chat e forneça apenas contexto autorizado.
+4. Não presumir que o Continue herda todas as instruções do Codex ou vice-versa: se necessário, inclua `AGENTS.md` como contexto autorizado.
+5. OpenRouter e outros provedores online recebem conteúdo enviado para inferência; obtenha G0 e jamais transmita `.env`, segredos, dados reais ou código corporativo sem aprovação.
+6. Verifique custo, limite da API Key e funções de autocomplete automático antes de habilitá-las.
+
+A regra global da extensão pode exigir instalação ou configuração adicional; o exemplo aqui é local ao workspace do projeto.
+
+Antes de atuar, carregue a matriz em `docs/WORKFLOW.md` e confira isolamento conforme `rules/git-workflow.md`. Registre aprovações somente em DECISIONS, referenciando IDs. Para banco, aplique `rules/database.md`: MANUAL_SQL padrão; G4 não autoriza execução. Não executar migrations/seeders/escrita sem modo permitido e DB_EXEC específico. Essas regras não substituem permissões técnicas.
+
+## Produção e SQL
+Produção permanece bloqueada por padrão. Operações de produção exigem as autorizações humanas específicas do workflow, incluindo G6 para a ação e o ambiente concretos. Operações de banco exigem também G2, DB_CHANGE e DB_EXEC aplicáveis, com executor, alvo e revisão dos scripts identificados; produção exige backup validado, plano de execução, validação e rollback. G4, G5 ou G6 não implicam autorização automática para executar SQL.
+
+MANUAL_SQL permanece como modo padrão: o agente apenas prepara os arquivos SQL e as instruções; a execução é responsabilidade humana, sujeita às autorizações aplicáveis. Nenhuma ferramenta deve executar comandos de escrita no banco sem autorização explícita para a operação e o ambiente. Para execução pelo agente, exigir também modo permitido escolhido pelo humano conforme `rules/database.md`; DB_EXEC humano não autoriza execução pelo agente. Essas instruções não substituem permissões técnicas.

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "ai-dev-workflow-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.0",
+  "description": "Instalador local e diagnóstico do AI Dev Workflow",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": "24.x"
+  },
+  "bin": {
+    "ai-dev-workflow": "bin/ai-dev-workflow.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "catalog/",
+    "payload/",
+    "AGENTS.md",
+    "rules/",
+    "agents/",
+    "templates/",
+    "stacks/",
+    "docs/WORKFLOW.md",
+    "docs/CLI.md",
+    "docs/QUICKSTART.md",
+    "integrations/",
+    ".continue/",
+    ".github/pull_request_template.md",
+    ".gitignore",
+    "LICENSE",
+    "scripts/check-catalog.js",
+    "docs/DISCOVERY_CLI.md",
+    "CLAUDE.md",
+    "GEMINI.md",
+    "docs/MULTI_AI.md",
+    "docs/PERSISTENCE.md",
+    "docs/LAYOUT.md"
+  ],
+  "scripts": {
+    "test": "node --test test/commands.test.js test/installer.test.js test/safety.test.js test/package.test.js test/recovery.test.js test/git-paths.test.js test/exit-codes.test.js test/git-storage.test.js test/layout.test.js test/discovery.test.js test/discovery-corrections.test.js test/multi-ai.test.js test/cwd.test.js test/persistence.test.js",
+    "validate:catalog": "node scripts/check-catalog.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/payload/central/.ai-dev-workflow/agents/architect.md

@@ -0,0 +1,5 @@
+# Papel: Architect / Planner
+
+Novo projeto: requisitos, trade-offs, ADR, componentes e esquema inicial. Legado: planejar mudança preservando contratos. Sempre listar critérios de aceitação, riscos, estimativa qualitativa, dependências, migração, testes e rollback. Não criar implementação sem G4.
+
+Em projeto novo, planejar bootstrap em P04 sobre baseline de pré-implementação aprovada em G3; não antecipar scaffold. Registrar modo do banco herdado/escolhido, DB_CHANGE e DB_EXEC separados de G4. Em MANUAL_SQL planejar entrega de SQL e roteiro conforme DATABASE_CHANGE, sem execução. Usar a matriz de regras e IDs canônicos de DECISIONS.