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

package/payload/legacy-v1/templates/DISCOVERY.md

@@ -0,0 +1,13 @@
+# Discovery — [projeto]
+Data: [AAAA-MM-DD] | Trilha: existente | Responsável: [...] | Status G1: pendente
+## Escopo/limitações
+## Evidências (caminho:linha ou comando seguro)
+## Stack (declarada / confirmada)
+| Camada | Tecnologia | Versão declarada | Versão confirmada | Evidência |
+|---|---|---|---|---|
+## Mapa de módulos e fluxos
+## Banco de dados (sem dados reais)
+## Dependências e pontos críticos
+## Riscos e lacunas
+## Próximas ações propostas
+## Aprovação G1 (quem, quando, escopo)

package/payload/legacy-v1/templates/ENVIRONMENT.md

@@ -0,0 +1,20 @@
+# Environment — [projeto]
+Status G1: [...] | Status G2: pendente
+## Pré-requisitos e versões compatíveis
+## SO / arquitetura / Docker
+## Serviços, portas e volumes
+## Variáveis de ambiente (somente nomes, sem valores secretos)
+## Comandos propostos (alvo e riscos)
+## Isolamento do banco de teste
+## Reprodução / troubleshooting
+## Testes de inicialização e evidências
+## Aprovação G2 da configuração (ID em DECISIONS)
+G2 não autoriza inicialização, migrations ou seeders.
+## Modo de operação de banco do projeto
+Modo: MANUAL_SQL (padrão até escolha humana explícita)
+Escolha DB_MODE (ID): [...] | Motor/versão real e evidência: [...]
+Alvos autorizados sem credenciais: [...]
+DB_CHANGE e DB_EXEC são separados e específicos por task/execução; ver `rules/database.md`.
+## Entrada e bootstrap
+Discovery (existente) ou REQUIREMENTS/ARCHITECTURE (novo), G1: [...]
+Projeto novo: não criar aplicação antes da task de bootstrap com G4.

package/payload/legacy-v1/templates/PR_CHECKLIST.md

@@ -0,0 +1,9 @@
+# Checklist de PR
+- [ ] Task e G4 documentados
+- [ ] Branch isolada; diff revisado
+- [ ] Sem credenciais, dumps nem dados reais
+- [ ] Testes relevantes executados e evidências anexadas
+- [ ] Compatibilidade validada; migrations/rollback planejados
+- [ ] Docs/CURRENT_STATE atualizados
+- [ ] Revisão G5 realizada
+- [ ] Deploy separado sujeito a G6

package/payload/legacy-v1/templates/REQUIREMENTS.md

@@ -0,0 +1,9 @@
+# Requirements — projeto novo
+## Problema / usuários / objetivo
+## Funcionalidades do MVP e fora do escopo
+## Requisitos funcionais e não funcionais
+## Dados e privacidade
+## Alternativas de stack e trade-offs
+## Critérios de aceitação
+## Riscos / perguntas abertas
+## Aprovação G1

package/payload/legacy-v1/templates/TASK.md

@@ -0,0 +1,26 @@
+# TASK-XXX — [título]
+Status: proposta | Branch: [feature/TASK-XXX-...] | Responsável: [...] | Aprovação G4: pendente
+## Contexto e objetivo
+## Fora do escopo
+## Requisitos e critérios de aceitação (verificáveis)
+## Arquivos/áreas possivelmente impactados
+## Dados, segurança e riscos
+## Plano de implementação (curto)
+## Plano de testes e ambiente
+## Rollback / reversão
+## Dependências e decisões abertas
+## Aprovação explícita G4
+
+## Isolamento e aprovações
+Raiz Git confirmada: [...] | Git-dir/common-dir: [...] | Branch efetiva: [...]
+IDs em `docs/project/DECISIONS.md`: [...] | Revisão dos artefatos: [...]
+Estados: pendente/aprovado/rejeitado/revogado/revalidação pendente. Escopo alterado exige revalidação.
+
+## Controle de banco (obrigatório, inclusive quando não aplicável)
+Banco envolvido: [sim/não/desconhecido; evidência]
+Modo do projeto: [MANUAL_SQL por padrão; herdar escolha humana vigente] | Modo efetivo da task: [...]
+Escolha humana/override DB_MODE (ID): [...] | Motor e versão real/evidência: [...]
+Alvo/ambiente sem credenciais: [...] | Executor: [...]
+G2 ambiente (ID): [...] | DB_CHANGE plano (ID): [...] | DB_EXEC execução concreta (ID): [...] | G6 produção, se aplicável: [...]
+**G4 não autoriza modificar banco. Sem DB_EXEC específico, não executar migrations, seeders, SQL de escrita ou scripts/testes que alterem banco. MANUAL_SQL proíbe execução pelo agente.**
+Entrega SQL/roteiro: `docs/tasks/TASK-XXX/sql/` conforme `templates/DATABASE_CHANGE.md`, ou não aplicável com justificativa.

package/payload/legacy-v1/templates/TASK_REPORT.md

@@ -0,0 +1,20 @@
+# TASK-XXX — Relatório de execução
+Data: [...] | Branch / commit: [...] | Status: [...]
+## Resumo da alteração
+## Arquivos criados/alterados
+## Testes executados
+| Comando | Ambiente | Resultado | Evidência/observação |
+|---|---|---|---|
+## Testes não executados e motivo
+## Segurança/compatibilidade e riscos restantes
+## Como reverter
+## Checklist para revisão G5
+## Próximas tarefas / CURRENT_STATE atualizado?
+
+## Controles de execução
+Raiz Git e branch verificadas: [...]
+IDs/revisões em DECISIONS e revalidações necessárias: [...]
+Modo de banco do projeto/task: MANUAL_SQL / [...]
+DB_CHANGE/DB_EXEC/G2/G6 aplicáveis: [...] | Executor e alvo: [...]
+SQL/roteiro entregues: [...] | Execução real e evidências: [...]
+Em MANUAL_SQL marcar: nenhuma escrita de banco executada pelo agente.

package/rules/cost-control.md

@@ -0,0 +1,6 @@
+# Controle de custo da IA
+- Dar tarefa curta, com caminhos e critérios explícitos; evitar anexar repositório inteiro.
+- Reusar CURRENT_STATE e task para não repetir análise.
+- Escolher modelos baratos/gratuitos para perguntas genéricas; modelo principal para mudanças críticas.
+- Cotas `:free` têm limites e podem mudar; modelos online podem processar contexto por terceiros.
+- Desligar ferramentas/autocomplete automático quando não necessários; verificar consumo do provedor.

package/rules/database.md

@@ -0,0 +1,46 @@
+# Banco de dados — controle obrigatório
+
+## Modo por projeto e por tarefa
+Registrar o modo do projeto em `docs/project/ENVIRONMENT.md` e a seleção efetiva em cada task. Sem escolha humana explícita, usar **MANUAL_SQL**. A task herda o modo do projeto; qualquer substituição exige escolha humana registrada em DECISIONS. Escolher um modo não autoriza executar operações.
+
+| Modo | Preparação | Execução pelo agente |
+| --- | --- | --- |
+| MANUAL_SQL | SQL versionado por task e roteiro para execução humana no phpMyAdmin | Proibida qualquer alteração de banco, mesmo local |
+| AUTOMATIC_LOCAL | Plano, scripts/migrations e verificações | Somente local ou ambiente isolado confirmado, com G2, DB_CHANGE e DB_EXEC aprovados |
+| PRODUCTION_CONTROLLED | Plano específico de produção, backup validado, validação e rollback | Somente com G2 do alvo, DB_CHANGE, DB_EXEC e G6 específicos aprovados; respeitar permissões da ferramenta |
+
+MANUAL_SQL é o padrão inclusive quando a stack oferece migrations. Não executar migrations, seeders, SQL de escrita, inicialização de bases, testes ou scripts que modifiquem banco sem autorização específica. Em MANUAL_SQL o agente apenas prepara os artefatos; para executar deve haver mudança explícita de modo e autorização separada. Testes com escrita também contam como execução de banco.
+
+## Aprovações cumulativas e independentes
+- **G2:** aprova configuração, isolamento e destino do ambiente; não autoriza escrita.
+- **G4:** aprova a implementação da task; não autoriza modificar banco.
+- **DB_CHANGE:** aprova o plano da mudança de schema/dados, scripts, riscos, backup, validação e reversão. Não autoriza executá-lo.
+- **DB_EXEC:** autoriza uma execução concreta pelo executor identificado (humano ou agente), sobre alvo e artefato/revisão identificados, com janela, comandos e limites. Para execução manual humana, registrar também DB_CHANGE e DB_EXEC antes da execução; isso não concede execução ao agente.
+- **G6:** autoriza operação de produção concreta, cumulativa com os controles de banco quando aplicáveis.
+
+Registrar os IDs e estados conforme `docs/WORKFLOW.md`. Um mesmo pedido humano pode conceder várias aprovações apenas se explicitar cada ação e alvo. Nunca inferir DB_EXEC de G2, G4, G5, G6 ou da escolha de modo. Após mudança de script, alvo ou escopo, suspender execução até revalidação. DB_EXEC vale para a execução registrada; repetição ou retry exige autorização específica, salvo se já delimitado explicitamente.
+
+## Preparação e verificação do alvo
+Inspecionar schema, FKs, índices e migrations antes de propor mudança. Confirmar motor, versão real, host/ambiente, banco, privilégios e isolamento sem registrar credenciais. Não usar somente a versão declarada em dependências. Se essas evidências faltarem, solicitar metadados sanitizados e bloquear o SQL executável dependente delas. Separar conexões por ambiente; não usar produção como fixture sem anonimização aprovada. Dados reais continuam sujeitos às regras de privacidade.
+
+## Entrega MANUAL_SQL
+Usar `templates/DATABASE_CHANGE.md` e `docs/tasks/TASK-XXX/sql/`:
+- `01-precheck.sql`: consultas de leitura sobre versão, schema e pré-condições, sem dados pessoais.
+- `02-change.sql`: alteração revisável, compatível com a versão real do MySQL ou MariaDB, charset/collation, engine e SQL mode confirmados.
+- `03-postcheck.sql`: consultas de leitura com resultados esperados e critérios de falha.
+- `04-rollback.sql`: somente quando tecnicamente seguro; caso contrário documentar irreversibilidade e restauração/compensação necessária.
+- `README.md`: ordem e seleção do banco no phpMyAdmin, conferência do alvo e versão, backup necessário e validação de restauração, autorizações, execução manual por etapas, resultados esperados, riscos e condições de parada. Não colar credenciais ou resultados sensíveis.
+
+Os SQL são artefatos da task; nenhum é executado automaticamente. Não prometer rollback transacional de DDL nem reversão de perda de dados; avaliar suporte e commits implícitos na versão confirmada. Registrar locks, impacto, dependências e risco de repetição. Idempotência somente quando demonstrável. Se phpMyAdmin/motor MySQL ou MariaDB não se aplicar, preservar MANUAL_SQL sem execução e acordar interface e dialeto reais antes de preparar a entrega; nunca presumir stack.
+
+## Restrições
+`DROP`, `TRUNCATE`, `DELETE` sem filtro, `migrate:fresh`, `db:wipe` e equivalentes continuam proibidos sem autorização específica da ação destrutiva. Um plano de rollback destrutivo também precisa de autorização para execução. Não executar rollback automaticamente. Migrations são uma opção de implementação versionada, nunca uma autorização implícita.
+
+Antes da entrega, verificar se os SQL revisados da task não estão ignorados pelo Git. Scripts de precheck, alteração aprovada, postcheck e reversão podem ser versionados em `docs/tasks/TASK-XXX/sql/`; backups, dumps e arquivos sensíveis devem permanecer nos locais ignorados e fora da entrega. Sinalizar qualquer exclusão inesperada, sem forçar staging ou alterar proteções implicitamente.
+
+O Git e o `.gitignore` não garantem ausência de dados sensíveis: arquivos já rastreados e SQL fora dos diretórios protegidos exigem inspeção. Todo SQL deve passar por revisão humana de conteúdo, dados, alvo e riscos antes de ser versionado. Não incluir dumps, credenciais, dados pessoais ou dados reais; scripts de dados devem usar conteúdo sintético ou parâmetros sem valores sensíveis. Poder versionar um arquivo não autoriza executar seu SQL nem fazer commit/push.
+
+## Bloqueio padrão de produção e ferramentas
+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/rules/general.md

@@ -0,0 +1,7 @@
+# Regras gerais
+- Confirmar trilha e fase.
+- Basear afirmações em arquivos/comandos reais e citar caminhos.
+- Alterações mínimas e reversíveis; evitar escopo ampliado.
+- Separar fatos, hipóteses e recomendações.
+- Declarar impedimentos, não esconder testes não executados.
+- Resumo final: objetivo, diff, testes, riscos, próximos passos.

package/rules/git-workflow.md

@@ -0,0 +1,16 @@
+# Git workflow
+- Inspecionar `git status` antes de iniciar; não sobrescrever alterações preexistentes.
+- Trabalhar em `feature/TASK-xxx-descricao`, `fix/TASK-xxx-descricao`, `docs/TASK-xxx-descricao` conforme o caso.
+- Branch protegida (`main`/`master`); nunca push/merge sem autorização.
+- Commit pequeno e descritivo `feat:`, `fix:`, `docs:`, `test:`, `chore:`.
+- Revisar diff, conflitos, segredos e arquivos não rastreados; PR inclui testes, risco e rollback.
+
+## Verificação de isolamento antes de alterações
+Executar no diretório autorizado: `pwd`, `git rev-parse --show-toplevel`, `git rev-parse --absolute-git-dir`, `git rev-parse --git-common-dir`, `git status --short --branch` e `git symbolic-ref --short HEAD`. Confirmar caminhos reais, inclusive symlinks, e comparar a raiz com o projeto autorizado. Repositórios aninhados, submódulos ou worktrees com metadados externos exigem confirmação do escopo antes de qualquer escrita Git. HEAD destacado exige branch de task antes de editar.
+
+Se a raiz for um diretório pai ou outro projeto, interromper alterações. Não executar `git add`, criar branch ou inicializar repositório nesse pai; não apagar/mover seu `.git`. Pedir definição explícita do limite correto. Não sobrescrever alterações preexistentes; arquivos não rastreados também são trabalho existente.
+
+## Inicialização segura
+Inicializar somente mediante autorização explícita para o diretório concreto, após confirmar caminho real e ausência de `.git` local. Se um pai já for repositório, informar que será criado um repositório aninhado e obter autorização específica. Não modificar o repositório pai nem aplicações vizinhas.
+
+No diretório confirmado, `git init` cria apenas os metadados locais; conferir novamente a raiz e o git-dir. Criar branch dedicada com `git switch -c docs/TASK-XXX-descricao` (ou feature/fix conforme tarefa), inclusive sem commits, e verificar a branch efetiva antes de editar. Se falhar por permissões ou versão da ferramenta, parar e resolver sem alterar em main. Não usar `git add .`, commit inicial, remote ou push como parte implícita da inicialização. Branch de task não autoriza commit/push/merge.

package/rules/security.md

@@ -0,0 +1,11 @@
+# Segurança e privacidade
+- Autorização G0 para transmitir código/dados a IA externa; respeitar contrato/política da organização.
+- Não abrir/transmitir `.env`, tokens, dumps reais, dados pessoais ou segredos; não versionar chaves de API.
+- Não executar ações destrutivas/produção sem aprovação explícita e específica; conferir alvo `APP_ENV`, host, banco e branch.
+- Proteção por permissões de ferramenta, ambiente e revisão humana; prompts não são barreiras de segurança.
+- Para acesso à nuvem, aplicar princípio do menor privilégio.
+- Redigir evidências com dados sintéticos, nunca credenciais.
+
+- Para banco, G2/G4 não autorizam escrita: aplicar modo efetivo, DB_CHANGE e DB_EXEC de `rules/database.md`; produção exige G6 específico e backup validado.
+
+G4, G5 e G6 não substituem DB_EXEC. Produção permanece bloqueada por padrão; qualquer escrita por ferramentas exige autorização explícita da operação, ambiente e executor, em modo permitido. Em MANUAL_SQL a execução é humana; o agente apenas prepara os artefatos. Git e .gitignore não garantem ausência de dados sensíveis: revisar todo SQL antes de versionar e manter dumps/backups/segredos fora da entrega.

package/rules/testing.md

@@ -0,0 +1,6 @@
+# Testes e evidências
+- Baseline antes de refatorar legado.
+- Preferir testes automatizados; smoke HTTP, autenticação, autorização, dados inválidos e regressões.
+- Registrar comando, ambiente, data, resultado e limitações.
+- Testes que alteram banco exigem base de teste isolada confirmada, G2, DB_CHANGE e DB_EXEC específicos, em AUTOMATIC_LOCAL. MANUAL_SQL permite apenas preparar o procedimento; não executar testes com escrita, mesmo com rollback. Seguir `rules/database.md`.
+- Não reportar PASS sem execução.

package/scripts/check-catalog.js

@@ -0,0 +1,11 @@
+import { loadCatalog, contextEntries } from '../src/core/catalog.js';
+import { validationFindings } from '../src/core/diagnostics.js';
+for (const [layout, version] of [['central-v2','0.3.0'],['central-v2','0.2.0'],['legacy-v1','0.1.0']]) {
+  const catalog = await loadCatalog(layout, version);
+  const allowed = new Set([...catalog.entries, ...contextEntries('new', layout)].map(e => e.path));
+  const findings = catalog.entries.flatMap(e => e.path.endsWith('.md') ? validationFindings(e.path, e.content, allowed) : []);
+  if (findings.length) {
+    console.error(JSON.stringify(findings, null, 2));
+    process.exitCode = 1;
+  } else console.log(`OK ${layout}/${version}: ${catalog.entries.length} arquivos explícitos, hashes e referências do catálogo.`);
+}

package/src/cli.js

@@ -0,0 +1,88 @@
+import { parseArgs } from 'node:util';
+import { resolveTarget } from './platform/filesystem.js';
+import { packageVersion } from './core/catalog.js';
+import { WorkflowError, fail } from './core/errors.js';
+import { run as init } from './commands/init.js';
+import { run as doctor } from './commands/doctor.js';
+import { run as status } from './commands/status.js';
+import { run as discover } from './commands/discover.js';
+import { run as validate } from './commands/validate.js';
+import { preflight, persist } from './persistence/record.js';
+import { prepareInit } from './interaction/init.js';
+import { renderText } from './output/text.js';
+import { renderJson } from './output/json.js';
+const help = `ai-dev-workflow <init|doctor|status|validate|discover> [--target <diretorio>]
+--target omitido usa process.cwd(); não procura outra raiz nem sobe diretórios.
+Git 2.28+ é necessário para init/doctor; Git nunca é inicializado automaticamente.
+init em TTY sem flags de automação oferece plano e confirmação padrão N; fora desse modo requer --track new|existing. discover admite --allow-no-git somente para ausência real de Git. Opções: --dry-run --json --help --version. --save grava registros locais opt-in; incompatível com --dry-run.
+Node.js 24 somente para a CLI; nenhum comando acessa banco, rede ou runtime da aplicação.
+`;
+export async function main(args, io = { out: text => process.stdout.write(text), err: text => process.stderr.write(text) }) {
+  let json = args.includes('--json');
+  try {
+    if (Number(process.versions.node.split('.')[0]) !== 24) fail('NODE_VERSION', 'Execute a CLI com Node.js 24 isolado da aplicação.', 1);
+    let parsed;
+    try {
+      parsed = parseArgs({ args, allowPositionals: true, options: {
+        target: { type: 'string' }, track: { type: 'string' }, 'dry-run': { type: 'boolean' },
+        'allow-no-git': { type: 'boolean' }, save: { type: 'boolean' }, json: { type: 'boolean' }, help: { type: 'boolean' }, version: { type: 'boolean' }
+      } });
+    } catch { fail('ARGUMENTS', 'Argumentos inválidos. Use --help.', 3); }
+    const { values, positionals } = parsed;
+    json = values.json ?? false;
+    if (values.save && values['dry-run']) fail('ARGUMENTS', '--save e --dry-run são incompatíveis; nenhuma escrita.', 3);
+    if (values.help || values.version) {
+      const result = { ok: true, message: values.version ? await packageVersion() : help.trim() };
+      io.out(json ? renderJson(result) : result.message + '\n'); return 0;
+    }
+    const command = positionals[0];
+    if (positionals.length !== 1 || !['init', 'doctor', 'status', 'validate', 'discover'].includes(command) ||
+      values.target === '' || (command === 'init' && values.track !== undefined && !['new', 'existing'].includes(values.track)) ||
+      (command !== 'init' && values.track !== undefined) ||
+      (command !== 'discover' && values['allow-no-git'] !== undefined))
+      fail('ARGUMENTS', 'Informe comando válido e, para init, --track new|existing. --target é opcional, mas não pode ser vazio. Use --help.', 3);
+    const interactiveInit = !process.env.CI && command === 'init' && values.track === undefined && !json && !values['dry-run'] &&
+      !!(io.input ?? process.stdin).isTTY && !!(io.output ?? process.stdout).isTTY;
+    if (command === 'init' && values.track === undefined && !interactiveInit)
+      fail('ARGUMENTS', 'Init sem interação requer --track new|existing. Use um terminal TTY para o assistente; CI, --json e --dry-run não fazem perguntas.', 3);
+    let input = values.target;
+    if (input === undefined) {
+      try { input = process.cwd(); }
+      catch { fail('CWD_UNAVAILABLE', 'Diretório atual indisponível. Use um diretório acessível ou --target absoluto explícito.', 1); }
+    }
+    const target = await resolveTarget(input);
+    if ((command === 'init' && !values['dry-run']) || values.save) io.err(`Destino canonicalizado: ${target}\n`);
+    if (values.save) await preflight(target,command,!!values['allow-no-git']);
+    if (interactiveInit) {
+      const prepared = await prepareInit(target,io);
+      if (prepared.result) {
+        io.out(renderText({ command, canonicalTarget:target, ...prepared.result }));
+        return prepared.result.exitCode ?? (prepared.result.ok ? 0 : 2);
+      }
+      values.track = prepared.track;
+    }
+    const execute = async () => command === 'discover' ? await discover({ target, allowNoGit: !!values['allow-no-git'] }) : command === 'init' ? await init({ target, track: values.track, dryRun: !!values['dry-run'] }) :
+      await ({ doctor, status, validate })[command](target);
+    let result;
+    if (values.save) {
+      try { result = await execute(); }
+      catch (e) { result = {ok:false,exitCode:e instanceof WorkflowError?e.exitCode:1,code:e instanceof WorkflowError?e.code:'IO_ERROR',message:e instanceof WorkflowError?e.message:'Falha operacional local; nenhum detalhe sensível exibido.'}; }
+    } else result = await execute();
+    const response = { command, canonicalTarget: target, ...result, ...(values['dry-run'] ? { dryRun: true } : {}) };
+    if (values.save) {
+      response.operationExitCode=result.exitCode??(result.ok?0:2);
+      try { response.persistence=await persist(target,command,result,!!values['allow-no-git']); }
+      catch(e) { response.persistence={ok:false,writeState:'incomplete-or-unknown',code:e instanceof WorkflowError?e.code:'IO_ERROR',message:'Persistência não concluída; preservar evidências e revisar sem repetir init automaticamente.'};response.ok=false;response.exitCode=e.exitCode??1; }
+    }
+    io.out(json ? renderJson(response) : renderText(response));
+    if (interactiveInit && response.ok) io.out('Próximos passos neste projeto: npx ai-dev-workflow-cli discover, npx ai-dev-workflow-cli doctor e npx ai-dev-workflow-cli status.\nA CLI não instala automaticamente Codex, Continue, Claude Code ou Gemini CLI.\n');
+    if (!json && command==='discover' && !values.save && result.ok) io.out('Para salvar este diagnóstico, use discover --save, mantendo o mesmo destino.\n');
+    return response.exitCode??result.exitCode ?? (result.ok ? 0 : 2);
+  } catch (error) {
+    const known = error instanceof WorkflowError;
+    const result = { ok: false, code: known ? error.code : 'IO_ERROR',
+      message: known ? error.message : 'Falha operacional local. Confira permissões e integridade; nenhum detalhe sensível foi exibido.' };
+    (json ? io.out : io.err)(json ? renderJson(result) : renderText(result));
+    return known ? error.exitCode : 1;
+  }
+}

package/src/commands/discover.js

@@ -0,0 +1,2 @@
+import { discover } from '../discovery/report.js';
+export const run = ({ target, allowNoGit = false }) => discover(target, allowNoGit);

package/src/commands/doctor.js

@@ -0,0 +1 @@
+export { doctor as run } from '../core/diagnostics.js';

package/src/commands/init.js

@@ -0,0 +1,2 @@
+import { install } from '../core/installer.js';
+export const run = options => install(options.target, options.track, options.dryRun);

package/src/commands/status.js

@@ -0,0 +1 @@
+export { status as run } from '../core/diagnostics.js';

package/src/commands/validate.js

@@ -0,0 +1 @@
+export { validateInstallation as run } from '../core/diagnostics.js';

package/src/core/adapters.js

@@ -0,0 +1,9 @@
+import { checkedPath, stat, readKnown } from '../platform/filesystem.js';
+import { fail } from './errors.js';
+export async function readInstalledEntry(root, relative) {
+  if (['CLAUDE.md','GEMINI.md'].includes(relative)) {
+    const info = await stat(await checkedPath(root, relative));
+    if (info && info.nlink !== 1) fail('UNSAFE_PATH', 'Hardlink em adaptador: isolamento não comprovado.');
+  }
+  return readKnown(root, relative);
+}

package/src/core/catalog.js

@@ -0,0 +1,52 @@
+import fs from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { hash, readKnown, safeRelative } from '../platform/filesystem.js';
+import { fail } from './errors.js';
+export const packageRoot = fileURLToPath(new URL('../../', import.meta.url));
+export const semver = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+export const sha256 = /^[a-f0-9]{64}$/;
+export const manifestPath = '.ai-dev-workflow/install.json';
+export const manifestVersion = '2.0.0';
+const allowedLegacy = /^(AGENTS\.md|rules\/[^/]+\.md|agents\/[^/]+\.md|templates\/[^/]+\.md|stacks\/[^/]+\.md|docs\/WORKFLOW\.md|integrations\/[^/]+\/README\.md|\.continue\/(rules|prompts)\/[^/]+\.md|\.github\/pull_request_template\.md|\.gitignore)$/;
+const centralTarget = value => ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md', '.gitignore', '.github/pull_request_template.md'].includes(value) ||
+  /^\.continue\/(rules|prompts)\/[^/]+\.md$/.test(value) ||
+  (value.startsWith('.ai-dev-workflow/') && /^(agents|rules|stacks|templates|integrations|docs)\//.test(value.slice(17)) && allowedLegacy.test(value.slice(17)));
+export async function loadCatalog(layout = 'central-v2', templateVersion = layout === 'legacy-v1' ? '0.1.0' : '0.3.0') {
+  if (!['central-v2', 'legacy-v1'].includes(layout)) fail('UNSUPPORTED_LAYOUT', 'Layout não suportado.');
+  const legacy = layout === 'legacy-v1';
+  if (!(legacy ? templateVersion === '0.1.0' : ['0.2.0','0.3.0'].includes(templateVersion))) fail('VERSION_PLAN_REQUIRED', 'Template não suportado; nenhuma migração será executada.');
+  const prior = !legacy && templateVersion === '0.2.0';
+  const file = legacy ? 'legacy-v1.json' : prior ? 'central-v0.2.json' : 'template.json';
+  const catalog = JSON.parse(await fs.readFile(new URL('../../catalog/' + file, import.meta.url), 'utf8'));
+  if (catalog.templateVersion !== templateVersion || catalog.catalogVersion !== (legacy ? '1.0.0' : '2.0.0') ||
+      (!legacy && catalog.layoutVersion !== layout) || !Array.isArray(catalog.files)) fail('INVALID_CATALOG', 'Catálogo inválido.');
+  const seen = new Set();
+  const entries = [];
+  for (const item of catalog.files) {
+    const target = legacy ? item.path : item.target;
+    const source = legacy ? item.path : item.source;
+    const asset = legacy ? 'payload/legacy-v1/' + target + (target === '.gitignore' ? '.txt' : '') : prior ? source.replace('payload/central/', 'payload/central-v0.2/') : source;
+    if (!safeRelative(target) || !safeRelative(source) || seen.has(target.toLowerCase()) || !sha256.test(item.sha256) ||
+        (legacy ? !allowedLegacy.test(target) : (prior && ['CLAUDE.md','GEMINI.md'].includes(target)) || !centralTarget(target) || source !== 'payload/central/' + target + (target === '.gitignore' ? '.txt' : '')))
+      fail('INVALID_CATALOG', 'Entrada fora da lista permitida do catálogo.');
+    if ([...seen].some(p => p.startsWith(target.toLowerCase() + '/') || target.toLowerCase().startsWith(p + '/')))
+      fail('INVALID_CATALOG', 'Colisão de arquivo e diretório no catálogo.');
+    const content = await readKnown(packageRoot, asset);
+    if (!content || hash(content) !== item.sha256) fail('CATALOG_INTEGRITY', `Integridade do template inválida: ${target}`);
+    seen.add(target.toLowerCase());
+    entries.push({ path: target, kind: target === '.gitignore' || (!legacy && !prior && ['CLAUDE.md','GEMINI.md'].includes(target)) ? 'custom' : 'managed', source, content });
+  }
+  if (entries.length !== (legacy || prior ? 38 : 40)) fail('INVALID_CATALOG', 'Inventário de fontes incompleto.');
+  return { ...catalog, readOnly: legacy || prior, layoutVersion: layout, manifestVersion: legacy ? '1.0.0' : '2.0.0', entries };
+}
+export async function packageVersion() {
+  return JSON.parse(await fs.readFile(new URL('../../package.json', import.meta.url), 'utf8')).version;
+}
+export function contextEntries(track, layout = 'central-v2') {
+  const phase = track === 'new' ? 'P00 Requirements & Architecture' : 'P01 Discovery';
+  return [
+    { path: 'docs/project/CURRENT_STATE.md', content: `# Estado atual\n\n## Trilha e fase inicial\nTrilha: ${track}\nFase inicial: ${phase}\n\n## Stack e ambiente\nNão verificados. O runtime Node.js 24 pertence somente à CLI.\n\n## Banco\nMANUAL_SQL (padrão). Nenhuma execução de banco autorizada.\n\n## Aprovações\nG0–G6, DB_MODE, DB_CHANGE e DB_EXEC pendentes quando aplicáveis.\nFonte canônica: docs/project/DECISIONS.md. Instalação não aprova fases.\n\n## Próximo passo\nRealizar a fase inicial autorizada e preencher evidências sem presumir resultados.\n` },
+    { path: 'docs/project/ENVIRONMENT.md', content: '# Ambiente do projeto\n\nModo de banco: MANUAL_SQL (padrão).\nMotor, versão, stack e ambiente: não verificados.\nG2: pendente. DB_CHANGE e DB_EXEC: pendentes quando aplicáveis.\nNenhuma execução autorizada; preencher a partir de templates/ENVIRONMENT.md.\n' },
+    { path: 'docs/project/DECISIONS.md', content: '# Registro canônico de decisões e aprovações\n\nNenhuma aprovação humana registrada pela instalação.\nG0–G6, DB_MODE, DB_CHANGE e DB_EXEC pendentes quando aplicáveis.\nUsar templates/DECISIONS.md; registrar manifestação humana, ação, alvo, executor e revisão.\n' }
+  ].map(e => ({ ...e, kind: 'custom', source: `generated:${track}`, content: Buffer.from(layout === 'legacy-v1' ? e.content : e.content.replaceAll('templates/', '.ai-dev-workflow/templates/')) }));
+}

package/src/core/diagnostics.js

@@ -0,0 +1,82 @@
+import { readKnown, hash } from '../platform/filesystem.js';
+import { inspectGit, assertGitMetadataIsolation } from '../platform/git.js';
+import { readInstalledEntry } from './adapters.js';
+import { safeRelative } from '../platform/filesystem.js';
+import { installedProfile } from './manifest.js';
+import { assertReconciled, checkContext } from './journal.js';
+import { fail, WorkflowError } from './errors.js';
+export async function inspectInstallation(root) {
+  await assertGitMetadataIsolation(root);
+  await assertReconciled(root);
+  await checkContext(root);
+  const profile = await installedProfile(root);
+  if (!profile) fail('NOT_INSTALLED', 'Manifesto ausente; execute init --dry-run para planejar instalação.');
+  const { catalog, manifest } = profile;
+  const files = [];
+  for (const entry of manifest.files) {
+    const current = await readInstalledEntry(root, entry.path);
+    const state = !current ? 'missing' : hash(current) === entry.installedHash ? 'unchanged' : entry.kind === 'custom' ? 'customized' : 'modified';
+    files.push({ path: entry.path, kind: entry.kind, state });
+  }
+  return { manifest, files, catalog };
+}
+export function validationFindings(path, content, allowedPaths) {
+  const findings = [];
+  const text = content.toString('utf8');
+  if (path.startsWith('.continue/') && path.endsWith('.md')) {
+    const fm = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+    const field = key => new RegExp(`^${key}:\\s*(.+)$`, 'm').exec(fm?.[1] ?? '')?.[1].trim();
+    if (!fm || !field('name') || (path.includes('/prompts/') && field('invokable') !== 'true') ||
+      (path === '.continue/rules/workflow.md' && field('alwaysApply') !== 'true'))
+      findings.push({ code: 'FRONTMATTER', path });
+  }
+  // Caminhos concretos de instrução; saídas de tasks e placeholders não são pré-requisitos.
+  for (const match of text.matchAll(/`((?:\.ai-dev-workflow|rules|agents|templates|integrations|stacks|docs|\.continue)\/[^`\n]+)`/g)) {
+    const ref = match[1];
+    if (/[<>*]/.test(ref) || /TASK-[Xx]+/.test(ref) || /\/$/.test(ref)) continue;
+    if (!allowedPaths.has(ref)) findings.push({ code: 'REFERENCE_MISSING', path, reference: ref });
+  }
+  if (['CLAUDE.md','GEMINI.md'].includes(path)) for (const match of text.matchAll(/^@([^\r\n]+)$/gm)) {
+    const ref = match[1].replace(/^\.\//, '');
+    if (!safeRelative(ref) || !allowedPaths.has(ref)) findings.push({ code: 'IMPORT_INVALID', path, reference: ref });
+  }
+  return findings;
+}
+export async function validateInstallation(root) {
+  const state = await inspectInstallation(root);
+  const findings = [];
+  const allowed = new Set(state.files.filter(f => f.state !== 'missing').map(f => f.path));
+  for (const file of state.files) {
+    if (['missing', 'modified'].includes(file.state)) findings.push({ code: file.state.toUpperCase(), path: file.path });
+    if (file.kind === 'managed' && file.state !== 'missing' && file.path.endsWith('.md')) {
+      findings.push(...validationFindings(file.path, await readKnown(root, file.path), allowed));
+    }
+  }
+  return { ok: !findings.length, exitCode: findings.length ? 2 : 0, findings, files: state.files,
+    layoutVersion: state.catalog.layoutVersion, readOnly: state.catalog.readOnly,
+    templateVersion: state.manifest.templateVersion, manifestVersion: state.manifest.manifestVersion,
+    message: (state.catalog.readOnly ? 'Perfil anterior somente leitura; init bloqueado. ' : '') + (findings.length ? 'Validação encontrou divergências; nenhum arquivo alterado.' : 'Estrutura, hashes e referências validados; aprovações humanas não verificadas automaticamente.') };
+}
+export async function status(root) {
+  const { manifest, files, catalog } = await inspectInstallation(root);
+  return { ok: true, layoutVersion: catalog.layoutVersion, readOnly: catalog.readOnly, templateVersion: manifest.templateVersion, cliVersion: manifest.cliVersion,
+    manifestVersion: manifest.manifestVersion, installedTrack: manifest.track, files,
+    approvals: 'Consultar docs/project/DECISIONS.md; a CLI não aprova gates.',
+    message: 'Contexto customizado é preservado; trilha exibida é a selecionada na instalação.' };
+}
+export async function doctor(root) {
+  const checks = [];
+  try { const git = await inspectGit(root); checks.push({ ...git, ok: git.safe }); }
+  catch (e) { checks.push({ code: e.code ?? 'IO_ERROR', ok: false, exitCode: e.exitCode ?? 1, message: 'Falha operacional na consulta Git.' }); }
+  try {
+    const validation = await validateInstallation(root);
+    checks.push({ code: 'INSTALLATION', layoutVersion: validation.layoutVersion, readOnly: validation.readOnly, ok: validation.ok, exitCode: validation.exitCode, message: validation.message, findings: validation.findings });
+  } catch (e) {
+    checks.push({ code: e instanceof WorkflowError ? e.code : 'IO_ERROR', ok: false, exitCode: e.exitCode ?? 1,
+      message: e instanceof WorkflowError ? e.message : 'Falha operacional na leitura da instalação.' });
+  }
+  const ok = checks.every(c => c.ok);
+  return { ok, checks, layoutVersion: checks.find(c => c.code === 'INSTALLATION')?.layoutVersion,
+    readOnly: checks.find(c => c.code === 'INSTALLATION')?.readOnly, exitCode: checks.some(c => c.exitCode === 1) ? 1 : ok ? 0 : 2,
+    message: 'Diagnóstico somente leitura; nenhum reparo, banco ou acesso externo executado.' };
+}

package/src/core/errors.js

@@ -0,0 +1,10 @@
+export class WorkflowError extends Error {
+  constructor(code, message, exitCode = 2) {
+    super(message);
+    this.code = code;
+    this.exitCode = exitCode;
+  }
+}
+export function fail(code, message, exitCode) {
+  throw new WorkflowError(code, message, exitCode);
+}

package/src/core/install-plan.js

@@ -0,0 +1,49 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { hash, checkedPath, stat } from '../platform/filesystem.js';
+import { contextEntries, loadCatalog, packageVersion } from './catalog.js';
+import { makeManifest, installedProfile } from './manifest.js';
+import { assertReconciled, checkContext } from './journal.js';
+import { readInstalledEntry } from './adapters.js';
+import { fail } from './errors.js';
+export async function planInstallation(root, track) {
+  await assertReconciled(root);
+  await checkContext(root);
+  const installed = await installedProfile(root);
+  if (installed?.catalog.layoutVersion === 'legacy-v1') fail('LEGACY_READ_ONLY', 'Instalação legada: somente doctor/status/validate. Init não migra nem repara; revisão humana necessária.');
+  if (installed?.catalog.readOnly) fail('TEMPLATE_READ_ONLY', 'Template anterior: somente inspeção; init não atualiza nem repara instalações existentes.');
+  if (!installed) await checkEmptyNamespace(root);
+  const catalog = await loadCatalog();
+  const entries = [...catalog.entries, ...contextEntries(track)];
+  const previous = installed?.manifest ?? null;
+  if (previous && previous.track !== track) fail('TRACK_CONFLICT', 'Trilha já instalada difere; alteração requer plano humano.');
+  const plan = [];
+  for (const entry of entries) {
+    const current = await readInstalledEntry(root, entry.path);
+    const initialHash = hash(entry.content);
+    const prior = previous?.files.find(f => f.path === entry.path);
+    let action = 'create';
+    if (current) {
+      action = hash(current) === initialHash ? 'unchanged' : entry.kind === 'custom' ? 'preserve-custom' : 'conflict';
+    } else if (prior?.kind === 'custom') {
+      action = 'conflict'; // não recriar contexto perdido com defaults que apaguem decisões
+    }
+    plan.push({ ...entry, action, installedHash: prior?.installedHash ?? (current ? hash(current) : initialHash) });
+  }
+  return { catalog, previous, plan, manifest: makeManifest(catalog, await packageVersion(), track, plan) };
+}
+
+async function checkEmptyNamespace(root) {
+  const directory = await checkedPath(root, '.ai-dev-workflow/install.json');
+  const parent = path.dirname(directory);
+  if (!await stat(parent)) return;
+  const names = await fs.readdir(parent);
+  for (const name of names) {
+    const info = await stat(path.join(parent, name));
+    if (info?.isSymbolicLink() || (info && !info.isDirectory() && !info.isFile())) fail('UNSAFE_PATH', 'Link ou arquivo especial no namespace central.');
+    if (['agents', 'rules', 'templates', 'stacks', 'integrations', 'docs'].includes(name) && !info?.isDirectory())
+      fail('UNSAFE_PATH', 'Diretório central ocupado por arquivo.');
+  }
+  if (names.some(name => !['install.lock', 'install-journal.jsonl'].includes(name)))
+    fail('NAMESPACE_CONFLICT', 'Namespace .ai-dev-workflow preexistente sem manifesto reconhecido; reconciliação humana necessária.');
+}

package/src/core/installer.js

@@ -0,0 +1,72 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createExclusive, checkedPath, readKnown, hash } from '../platform/filesystem.js';
+import { manifestPath } from './catalog.js';
+import { inspectGit } from '../platform/git.js';
+import { planInstallation } from './install-plan.js';
+import { startJournal, journalPath, checkContext } from './journal.js';
+import { fail, WorkflowError } from './errors.js';
+const lockPath = '.ai-dev-workflow/install.lock';
+export async function install(root, track, dryRun = false) {
+  const git = await inspectGit(root);
+  if (!git.safe) fail(git.code, git.message, git.exitCode);
+  const result = await planInstallation(root, track);
+  const operations = [...result.plan.map(({ path, kind, action }) => ({ path, kind, action })),
+    { path: manifestPath, kind: 'metadata', action: result.previous ? 'unchanged' : 'create' }];
+  if (result.plan.some(e => e.action === 'conflict'))
+    return { ok: false, exitCode: 2, code: 'CONFLICT', dryRun, operations, message: 'Conflitos detectados; nenhum arquivo escrito.' };
+  if (dryRun) return { ok: true, dryRun: true, operations, message: 'Plano somente leitura; journal e manifesto não foram criados.' };
+  let lock;
+  const created = [];
+  try {
+    lock = await checkedPath(root, lockPath);
+    await fs.mkdir(path.dirname(lock), { recursive: true });
+    await checkedPath(root, lockPath);
+    await fs.writeFile(lock, '', { flag: 'wx' });
+  } catch (e) {
+    if (e instanceof WorkflowError) throw e;
+    return { ok: false, exitCode: e.code === 'EEXIST' ? 2 : 1, code: e.code === 'EEXIST' ? 'INSTALL_LOCKED' : 'IO_ERROR',
+      message: 'Não foi possível obter lock local; nenhum arquivo do template escrito.', operations };
+  }
+  let response;
+  let journal;
+  try {
+    const check = await inspectGit(root);
+    if (!check.safe) fail(check.code, check.message, check.exitCode);
+    const fresh = await planInstallation(root, track);
+    if (fresh.plan.some(e => e.action === 'conflict')) fail('CONFLICT', 'Destino mudou desde o plano; execução interrompida.');
+    const pending = fresh.plan.filter(e => e.action === 'create');
+    if (!fresh.previous) pending.push({ path: manifestPath, kind: 'metadata', action: 'create',
+      content: Buffer.from(JSON.stringify(fresh.manifest, null, 2) + '\n') });
+    if (pending.length) {
+      // Intenção completa durável ANTES de qualquer escrita do template/contexto/manifesto.
+      const manifestEntry = pending.find(e => e.path === manifestPath);
+      journal = await startJournal(root, [...fresh.plan, ...(manifestEntry ? [manifestEntry] : [])], track, fresh.catalog.templateVersion, fresh.manifest);
+      for (const entry of pending) {
+        await createExclusive(root, entry.path, entry.content);
+        created.push(entry.path);
+        await journal.append({ event: 'created', path: entry.path, hash: hash(entry.content) });
+      }
+      for (const entry of pending) {
+        const actual = await readKnown(root, entry.path);
+        if (!actual || hash(actual) !== hash(entry.content)) fail('INSTALL_INCONSISTENT', 'Conteúdo criado diverge do plano; reconciliação humana necessária.');
+      }
+      await checkContext(root);
+      await journal.append({ event: 'completed' });
+      await journal.close();
+      // Somente esta execução bem-sucedida remove seu próprio journal.
+      await fs.unlink(journal.file);
+    }
+    response = { ok: true, operations, created, message: created.length ? 'Instalação concluída; nenhuma aprovação de workflow ou banco concedida.' : 'Instalação já equivalente; nenhum arquivo persistente alterado.' };
+  } catch (e) {
+    if (e.createdPath && !created.includes(e.createdPath)) created.push(e.createdPath);
+    response = { ok: false, exitCode: e.exitCode ?? 1, code: e.code ?? 'IO_ERROR', created, journal: journalPath,
+      message: 'Instalação interrompida. Journal e arquivos foram preservados; init/status/validate bloqueados até reconciliação humana segura.', operations };
+  } finally {
+    if (journal) await journal.close().catch(() => {});
+    try { await fs.unlink(lock); }
+    catch { response = { ...response, ok: false, exitCode: 1, code: 'LOCK_CLEANUP',
+      message: 'Não foi possível remover o lock desta execução; revisar lock e journal manualmente. Arquivos preservados.' }; }
+  }
+  return response;
+}