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

package/src/persistence/record.js

@@ -0,0 +1,90 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { checkedPath, stat, hash } from '../platform/filesystem.js';
+import { inspectGit, inspectDiscoveryGit } from '../platform/git.js';
+import { assertReconciled } from '../core/journal.js';
+import { packageVersion } from '../core/catalog.js';
+import { fail } from '../core/errors.js';
+import { paths, limits, read, absent, parent, exclusive, publish, syncParent } from './storage.js';
+import { parseHistory } from './history.js';
+import { discoveryMarkdown } from './markdown.js';
+async function safety(root,command,allowNoGit){
+  const noGit=command==='discover'&&allowNoGit&&!await stat(path.join(root,'.git'));
+  const g=noGit?await inspectDiscoveryGit(root,true):await inspectGit(root);
+  if(!g.safe)fail(g.code,'Persistência exige alvo Git seguro e branch de task, ou Discovery sem Git explicitamente permitido.',g.exitCode);
+  await assertReconciled(root);
+  await absent(root,paths.journal);
+}
+export async function preflight(root,command,allowNoGit){
+  await safety(root,command,allowNoGit);await absent(root,paths.lock);
+  parseHistory(await read(root,paths.history,limits.history));
+  if(command==='discover')await read(root,paths.current,limits.report);
+}
+export async function persist(root,command,result,allowNoGit=false){
+  await safety(root,command,allowNoGit);
+  const id=randomUUID();let lockInfo;let locked=false;let journalCreated=false;let preserveLock=false;
+  try{
+    await parent(root,paths.lock);
+    // exclusive cria antes de escrever; guardar propriedade mesmo se a escrita falhar.
+    const file=await checkedPath(root,paths.lock);let h;
+    try{h=await fs.open(file,'wx',0o600);}catch(e){if(e.code==='EEXIST')fail('PERSISTENCE_LOCKED','Outro gravador ou lock antigo está presente.');throw e;}
+    locked=true;
+    try{lockInfo=await h.stat();await h.writeFile(id+'\n');await h.sync();}finally{await h.close();}
+    await safety(root,command,allowNoGit);
+    const history=await read(root,paths.history,limits.history);const events=parseHistory(history);
+    const operationExitCode=result.exitCode??(result.ok?0:2);
+    const cliVersion=await packageVersion();
+    // Sob lock: instante de preparação do registro, não do comando. O relógio pode regredir.
+    const timestamp=new Date().toISOString();
+    const event={historyVersion:'1.0.0',id,timestamp,cliVersion,command,
+      result:operationExitCode===0?'completed':operationExitCode===1?'error':'blocked',operationExitCode,
+      summaryCode:['COMPLETED','OPERATIONAL_ERROR','BLOCKED','INVALID_ARGUMENTS'][operationExitCode]};
+    const entries=[];let canonical='not-applicable';
+    if(command==='discover'&&operationExitCode===0){
+      const report=discoveryMarkdown(result,id,timestamp);
+      const current=await read(root,paths.current,limits.report);
+      const previous=events.filter(e=>e.discovery).at(-1)?.discovery;
+      let owned=false;
+      if(previous){
+        const last=await read(root,paths.versions+'/'+previous.snapshot,limits.report);
+        if(!last||hash(last)!==previous.sha256)fail('HISTORY_INVALID','Última versão histórica ausente/adulterada; reconciliação humana necessária.');
+        owned=!!current&&hash(current)===previous.sha256;
+      }
+      canonical=!current?'created':owned?'updated':'preserved-custom';
+      event.discovery={snapshot:id+'.md',sha256:hash(report),current:canonical};
+      entries.push({path:paths.versions+'/'+id+'.md',data:report,beforeHash:null,maximum:limits.report});
+      if(!current||owned)entries.push({path:paths.current,data:report,beforeHash:current?hash(current):null,maximum:limits.report});
+    }
+    const line=Buffer.from(JSON.stringify(event)+'\n');if(line.length>limits.event)fail('PERSISTENCE_LIMIT','Evento excede limite.');
+    const next=Buffer.concat([history??Buffer.alloc(0),line]);if(next.length>limits.history)fail('PERSISTENCE_LIMIT','Histórico excede limite; nenhuma rotação automática.');
+    parseHistory(next); // Conferir schema gerado antes de qualquer publicação.
+    entries.push({path:paths.history,data:next,beforeHash:history?hash(history):null,maximum:limits.history});
+    entries.forEach((e,i)=>{e.temp=path.posix.dirname(e.path)+'/.record-'+id+'-'+i+'.tmp';});
+    for(const e of entries){await parent(root,e.path);await absent(root,e.temp);}
+    const plan={persistenceVersion:'1.0.0',id,event,files:entries.map(e=>({path:e.path,temp:e.temp,beforeHash:e.beforeHash,plannedHash:hash(e.data)}))};
+    // Até um journal vazio/truncado é evidência bloqueante; nunca removê-lo no erro.
+    journalCreated=true;await exclusive(root,paths.journal,Buffer.from(JSON.stringify(plan)+'\n'));await syncParent(root,paths.journal);
+    for(const entry of entries)await publish(root,entry);
+    for(const entry of entries){const value=await read(root,entry.path,entry.maximum);if(!value||hash(value)!==hash(entry.data))fail('PERSISTENCE_INCOMPLETE','Publicação divergente; preservar evidências.');}
+    await fs.unlink(await checkedPath(root,paths.journal));
+    try { await syncParent(root,paths.journal);journalCreated=false; }
+    catch(e) {
+      // Resultado do cleanup não comprovado: recolocar marcador ou manter lock.
+      try { await exclusive(root,paths.journal,Buffer.from(JSON.stringify(plan)+'\n')); }
+      catch { preserveLock=true; }
+      throw e;
+    }
+    return {ok:true,wrote:true,completed:true,id,history:paths.history,...(event.discovery?{snapshot:paths.versions+'/'+event.discovery.snapshot,current:canonical}:{}),message:'Registros publicados; não representam auditoria completa nem aprovação humana.'};
+  }catch(e){
+    // Mensagens constantes: não retornar conteúdo de arquivos, argv ou erro bruto.
+    if(journalCreated)e.persistenceIncomplete=true;
+    throw e;
+  }finally{
+    if(locked&&!preserveLock){
+      const file=await checkedPath(root,paths.lock);const now=await stat(file);
+      if(!lockInfo||!now||now.ino!==lockInfo.ino||now.dev!==lockInfo.dev||now.nlink!==1)fail('PERSISTENCE_LOCK_CLEANUP','Lock mudou; não remover automaticamente.',1);
+      await fs.unlink(file);
+    }
+  }
+}

package/src/persistence/storage.js

@@ -0,0 +1,47 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { constants } from 'node:fs';
+import { checkedPath, hash } from '../platform/filesystem.js';
+import { fail } from '../core/errors.js';
+export const paths = { history:'docs/project/COMMAND_HISTORY.jsonl', current:'docs/project/DISCOVERY.md', versions:'docs/project/discovery-history', lock:'docs/project/.command-history.lock', journal:'docs/project/.command-history-journal.json' };
+export const limits = { report:2*1024*1024, event:16*1024, history:8*1024*1024 };
+export async function read(root, relative, maximum) {
+  const file=await checkedPath(root,relative);let info;
+  try{info=await fs.lstat(file);}catch(e){if(e.code==='ENOENT')return null;throw e;}
+  if(info.nlink!==1)fail('PERSISTENCE_UNSAFE','Hardlink em arquivo de persistência.');
+  if(info.size>maximum)fail('PERSISTENCE_LIMIT','Limite de persistência excedido.');
+  const handle=await fs.open(file,constants.O_RDONLY|(constants.O_NOFOLLOW??0));
+  try{
+    const opened=await handle.stat();
+    if(opened.ino!==info.ino||opened.dev!==info.dev||opened.size!==info.size||opened.nlink!==1)fail('PERSISTENCE_UNSAFE','Arquivo alterado durante validação.');
+    const data=Buffer.alloc(info.size+1);let offset=0;
+    while(offset<data.length){const r=await handle.read(data,offset,data.length-offset,null);if(!r.bytesRead)break;offset+=r.bytesRead;}
+    const after=await handle.stat();
+    if(offset!==info.size||after.size!==info.size||after.mtimeMs!==opened.mtimeMs||after.nlink!==1)fail('PERSISTENCE_UNSAFE','Arquivo alterado durante leitura.');
+    return data.subarray(0,offset);
+  }finally{await handle.close();}
+}
+export async function absent(root,relative){
+  if(await fs.lstat(await checkedPath(root,relative)).catch(e=>{if(e.code==='ENOENT')return null;throw e;}))fail('PERSISTENCE_INCOMPLETE','Persistência ocupada/incompleta; preservar evidências e reconciliar manualmente.');
+}
+export async function parent(root,relative){
+  const file=await checkedPath(root,relative);await fs.mkdir(path.dirname(file),{recursive:true});await checkedPath(root,relative);return file;
+}
+export async function exclusive(root,relative,data){
+  const file=await parent(root,relative);const h=await fs.open(file,'wx',0o600);
+  try{await h.writeFile(data);await h.sync();return await h.stat();}finally{await h.close();}
+}
+export async function syncParent(root,relative){
+  const dir=path.dirname(await checkedPath(root,relative));const h=await fs.open(dir,'r');try{await h.sync();}finally{await h.close();}
+}
+export async function publish(root,entry){
+  await exclusive(root,entry.temp,entry.data);
+  const before=await read(root,entry.path,entry.maximum);
+  if((before?hash(before):null)!==entry.beforeHash)fail('PERSISTENCE_CONFLICT','Arquivo mudou; publicação bloqueada.');
+  const dest=await checkedPath(root,entry.path);const temp=await checkedPath(root,entry.temp);
+  if(before){await fs.rename(temp,dest);}else{
+    // Publicar sem substituir arquivo preexistente, inclusive UUID colidente.
+    await fs.link(temp,dest);await fs.unlink(temp);
+  }
+  await syncParent(root,entry.path);
+}

package/src/platform/filesystem.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { fail } from '../core/errors.js';
+export const hash = data => createHash('sha256').update(data).digest('hex');
+export async function stat(file) {
+  try { return await fs.lstat(file); }
+  catch (e) { if (e.code === 'ENOENT') return null; throw e; }
+}
+export function safeRelative(name) {
+  return typeof name === 'string' && name.length > 0 && !name.includes('\\') &&
+    !/[<>:"|?*\u0000-\u001F]/.test(name) && !path.posix.isAbsolute(name) &&
+    name.split('/').every(p => p && p !== '.' && p !== '..' && !/[. ]$/.test(p) &&
+      !/^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(p));
+}
+export async function resolveTarget(input) {
+  const absolute = path.resolve(input);
+  const parsed = path.parse(absolute);
+  let current = parsed.root;
+  const parts = absolute.slice(parsed.root.length).split(path.sep).filter(Boolean);
+  for (let i = 0; i < parts.length; i++) {
+    current = path.join(current, parts[i]);
+    const info = await stat(current);
+    if (!info) fail('TARGET_MISSING', 'Crie o diretório e prepare Git manualmente antes de init.');
+    if (info.isSymbolicLink()) {
+      const aliases = { '/tmp': '/private/tmp', '/var': '/private/var', '/etc': '/private/etc' };
+      const allowed = process.platform === 'darwin' && i < parts.length - 1 && aliases[current];
+      if (!allowed || await fs.realpath(current) !== aliases[current])
+        fail('UNSAFE_TARGET', 'Link/junction no destino ou ancestral não autorizado; use o destino real após revisão.');
+    } else if (!info.isDirectory()) fail('UNSAFE_TARGET', 'Destino e ancestrais devem ser diretórios.');
+  }
+  return fs.realpath(absolute);
+}
+export async function checkedPath(root, relative) {
+  if (!safeRelative(relative)) fail('UNSAFE_PATH', 'Caminho fora do contrato do template.');
+  const rootInfo = await stat(root);
+  if (rootInfo && (!rootInfo.isDirectory() || rootInfo.isSymbolicLink()))
+    fail('UNSAFE_TARGET', 'Raiz alterada ou insegura.');
+  let current = root;
+  const parts = relative.split('/');
+  for (let i = 0; i < parts.length; i++) {
+    current = path.join(current, parts[i]);
+    const info = await stat(current);
+    if (info?.isSymbolicLink()) fail('UNSAFE_PATH', `Link recusado: ${relative}`);
+    if (info && i < parts.length - 1 && !info.isDirectory())
+      fail('UNSAFE_PATH', `Diretório esperado: ${relative}`);
+    if (info && i === parts.length - 1 && !info.isFile())
+      fail('UNSAFE_PATH', `Arquivo regular esperado: ${relative}`);
+  }
+  return current;
+}
+export async function readKnown(root, relative) {
+  const file = await checkedPath(root, relative);
+  const info = await stat(file);
+  if (!info) return null;
+  if (info.size > 2 * 1024 * 1024) fail('FILE_TOO_LARGE', `Arquivo excede limite de 2 MiB: ${relative}`);
+  return fs.readFile(file);
+}
+export async function createExclusive(root, relative, content) {
+  const file = await checkedPath(root, relative);
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  // Revalidar depois da criação dos diretórios; wx nunca substitui um arquivo.
+  await checkedPath(root, relative);
+  const handle = await fs.open(file, 'wx', 0o644);
+  try { await handle.writeFile(content); await handle.sync(); }
+  catch (e) { e.createdPath = relative; throw e; }
+  finally {
+    try { await handle.close(); }
+    catch (e) { e.createdPath = relative; throw e; }
+  }
+}

package/src/platform/git.js

@@ -0,0 +1,123 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { stat, readKnown, checkedPath } from './filesystem.js';
+import { fail } from '../core/errors.js';
+
+const samePath = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+const blocked = (code, message) => ({ safe: false, code, message, exitCode: 2 });
+function runGit(root, args) {
+  // Sem shell, rede, hooks ou configurações globais; somente comandos fixos de inspeção.
+  const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !k.startsWith('GIT_')));
+  // Usar o caminho reconhecido pelo Git, inclusive Git for Windows, não os.devNull.
+  Object.assign(env, { GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null',
+    GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0', GIT_NO_REPLACE_OBJECTS: '1', LC_ALL: 'C' });
+  const r = spawnSync('git', ['--no-optional-locks', '-c', 'core.fsmonitor=false', ...args],
+    { cwd: root, env, encoding: 'utf8', shell: false, timeout: 10000, maxBuffer: 1024 * 1024, windowsHide: true });
+  if (r.error || r.signal) fail(r.error?.code === 'ENOENT' ? 'GIT_REQUIRED' : 'GIT_IO_ERROR',
+    'Git executável disponível e permissões de leitura são necessários para a ferramenta.', 1);
+  if (/permission denied|input\/output error|cannot allocate memory/i.test(r.stderr))
+    fail('GIT_IO_ERROR', 'Falha operacional ao consultar Git; confira permissões.', 1);
+  return { status: r.status, text: r.stdout.trim() };
+}
+// Inspeção somente por filesystem, compartilhada pelos quatro comandos.
+// Não seguir links nem abrir arquivos antes de validar a árvore completa.
+export async function assertGitMetadataIsolation(root) {
+  const marker = await stat(path.join(root, '.git'));
+  if (!marker) fail('GIT_MISSING', 'Metadados Git locais ausentes; preparação humana necessária.');
+  if (!marker.isDirectory() || marker.isSymbolicLink())
+    fail('GIT_EXTERNAL_METADATA', 'Metadados Git indiretos não são suportados.');
+  let count = 0;
+  const walk = async (relative, depth = 0) => {
+    if (++count > 100000 || depth > 64)
+      fail('GIT_METADATA_LIMIT', 'Metadados excedem o limite verificável (100000 entradas/64 níveis).');
+    const file = path.join(root, relative);
+    const info = await fs.lstat(file);
+    if (info.isSymbolicLink() || (!info.isDirectory() && !info.isFile()) || (info.isFile() && info.nlink !== 1))
+      fail('GIT_EXTERNAL_METADATA', 'Link, hardlink ou arquivo especial em metadados Git; isolamento não comprovado.');
+    if (!samePath(await fs.realpath(file), file))
+      fail('GIT_EXTERNAL_METADATA', 'Caminho Git redirecionado; isolamento não comprovado.');
+    const key = relative.toLowerCase();
+    // Bloquear mecanismos indiretos mesmo se o arquivo estiver vazio.
+    if (['.git/commondir', '.git/gitdir', '.git/config.worktree', '.git/objects/info/alternates',
+      '.git/objects/info/http-alternates', '.git/info/grafts', '.git/refs/replace', '.git/reftable'].includes(key) ||
+      (key.startsWith('.git/objects/') && key.endsWith('.promisor')))
+      fail('GIT_EXTERNAL_METADATA', 'Armazenamento Git compartilhado, promisor, grafts ou reftable não suportado.');
+    if (info.isDirectory()) {
+      for (const name of await fs.readdir(file)) await walk(relative + '/' + name, depth + 1);
+    }
+  };
+  await walk('.git');
+  for (const name of ['HEAD', 'config', 'objects', 'refs']) {
+    const info = await stat(path.join(root, '.git', name));
+    if (!info || (['objects', 'refs'].includes(name) ? !info.isDirectory() : !info.isFile()))
+      fail('GIT_INVALID', 'Metadados Git incompletos ou inseguros.');
+  }
+  const config = await readKnown(root, '.git/config');
+  if (/^\s*\[\s*include(?:if)?(?:\s|[.\]])/im.test(config.toString('utf8')) ||
+      /(?:^|\])\s*(?:worktree|worktreeconfig|promisor|partialclone|refstorage)\s*(?:=|[#;]|$)/im.test(config.toString('utf8')))
+    fail('GIT_EXTERNAL_METADATA', 'Configuração indireta, promisor ou armazenamento de refs alternativo não suportado.');
+}
+export async function inspectGit(root) {
+  return inspectRepository(root, false, false);
+}
+export async function inspectDiscoveryGit(root, allowNoGit = false) {
+  return inspectRepository(root, true, allowNoGit);
+}
+async function inspectRepository(root, discovery, allowNoGit) {
+  if (Object.keys(process.env).some(k => /^GIT_(DIR|WORK_TREE|COMMON_DIR|INDEX_FILE|OBJECT_DIRECTORY|ALTERNATE_OBJECT_DIRECTORIES|CONFIG.*)$/.test(k)))
+    return blocked('GIT_ENV_OVERRIDE', 'Remova overrides Git antes de usar a ferramenta.');
+  const marker = await stat(path.join(root, '.git'));
+  let parent = path.dirname(root);
+  while (true) {
+    if (await stat(path.join(parent, '.git')))
+      return blocked(marker ? 'GIT_NESTED' : 'GIT_PARENT', 'Repositório pai/aninhado detectado; revisão manual necessária.');
+    const next = path.dirname(parent);
+    if (next === parent) break;
+    parent = next;
+  }
+  if (!marker && discovery && allowNoGit) return { safe: true, code: 'NO_GIT_LIMITED', mode: 'no-git', exitCode: 0 };
+  if (!marker) return blocked('GIT_MISSING', 'Inicialize Git e crie branch de task manualmente, com autorização; a CLI não executa git init.');
+  if (!marker.isDirectory() || marker.isSymbolicLink())
+    return blocked('GIT_EXTERNAL_METADATA', 'Worktree/submódulo ou metadados indiretos exigem revisão manual.');
+  try { await assertGitMetadataIsolation(root); }
+  catch (e) {
+    if (e.exitCode === 2) return blocked(e.code, e.message);
+    throw e;
+  }
+  await checkedPath(root, '.git/packed-refs');
+  const headText = (await readKnown(root, '.git/HEAD')).toString('utf8');
+  if (headText.startsWith('ref:')) {
+    const candidate = /^ref: (refs\/heads\/[^\r\n]+)\r?\n?$/.exec(headText);
+    if (!candidate) return blocked('GIT_INVALID', 'Referência HEAD incompleta ou inválida.');
+    await checkedPath(root, `.git/${candidate[1]}`);
+  }
+  const top = runGit(root, ['rev-parse', '--show-toplevel']);
+  const inside = runGit(root, ['rev-parse', '--is-inside-work-tree']);
+  const bare = runGit(root, ['rev-parse', '--is-bare-repository']);
+  if (top.status || inside.status || bare.status || inside.text !== 'true' || bare.text !== 'false')
+    return blocked('GIT_INVALID', 'Repositório Git não reconhecido como árvore de trabalho válida.');
+  const gitDir = runGit(root, ['rev-parse', '--absolute-git-dir']);
+  const common = runGit(root, ['rev-parse', '--git-common-dir']);
+  if (gitDir.status || common.status || !samePath(await fs.realpath(top.text), root) ||
+    !samePath(await fs.realpath(gitDir.text), path.join(root, '.git')) ||
+    !samePath(await fs.realpath(path.resolve(root, common.text)), path.join(root, '.git')))
+    return blocked('GIT_ROOT_MISMATCH', 'Raiz ou metadados Git não correspondem ao alvo aprovado.');
+  const ref = runGit(root, ['symbolic-ref', '--quiet', 'HEAD']);
+  if (ref.status === 1 && discovery) {
+    if (runGit(root, ['rev-parse', '--verify', 'HEAD^{commit}']).status) return blocked('GIT_INVALID', 'HEAD destacado inválido.');
+    return { safe: true, code: 'GIT_OK', mode: 'git', head: 'detached', exitCode: 0 };
+  }
+  if (ref.status === 1) return blocked('GIT_DETACHED', 'HEAD destacado; crie branch de task manualmente.');
+  if (ref.status || !ref.text.startsWith('refs/heads/') || runGit(root, ['check-ref-format', ref.text]).status)
+    return blocked('GIT_INVALID', 'Referência HEAD/branch inválida.');
+  await checkedPath(root, `.git/${ref.text}`);
+  const branch = ref.text.slice('refs/heads/'.length);
+  if (!discovery && ['main', 'master'].includes(branch.toLowerCase()))
+    return blocked('GIT_PROTECTED', 'Branch protegida; crie branch de task antes da instalação.');
+  const commit = runGit(root, ['rev-parse', '--verify', 'HEAD^{commit}']);
+  // Um repositório novo pode ter branch válida ainda sem commit (unborn).
+  if (commit.status && runGit(root, ['show-ref', '--verify', '--quiet', ref.text]).status !== 1)
+    return blocked('GIT_INVALID', 'HEAD aponta para objeto ausente ou inválido.');
+  return { safe: true, code: 'GIT_OK', ...(discovery ? { mode: 'git', head: commit.status ? 'unborn' : 'attached' } : {}), message: 'Raiz, metadados e branch Git real verificados.', exitCode: 0 };
+}

package/stacks/nodejs.md

@@ -0,0 +1,3 @@
+# Node.js — checklist
+- Verificar `package.json`, lockfile, Node, scripts, build, env, testes, gerenciador de pacotes, dependências e banco.
+- Instalar usando lockfile no ambiente autorizado, sem upgrades implícitos.

package/stacks/php-laravel.md

@@ -0,0 +1,6 @@
+# PHP / Laravel — checklist
+- Identificar versões por `composer.json` e `composer.lock`, `php -v` se ambiente autorizado.
+- Mapear `artisan`, `routes/`, `app/`, `config/`, `database/migrations`, `tests/`.
+- Verificar versão do PHP, extensões, Composer, banco, Node e compatibilidade de pacotes.
+- Evitar atualizar Laravel/PHP durante mudanças urgentes; preparar plano em separado.
+- Comandos que criem/alterem banco, seeds e migrations seguem `rules/database.md`: MANUAL_SQL por padrão; G2 não autoriza execução. Exigir modo permitido, DB_CHANGE e DB_EXEC específicos. Não executar escrita em MANUAL_SQL.

package/stacks/php-native.md

@@ -0,0 +1,3 @@
+# PHP nativo — checklist
+- Identificar versão/extensões PHP, roteador/front controller, `.htaccess`/Nginx, composer (se existir), sessões, CSRF, SQL e estrutura pública.
+- Documentar configuração local, segurança e rotas sem reescrever arquitetura na Discovery.

package/stacks/wordpress.md

@@ -0,0 +1,4 @@
+# WordPress — checklist
+- Inventariar WordPress, PHP, plugins, tema, hooks, banco, checkout e integrações.
+- Nunca atualizar plugins ou tocar em produção antes de backup e testes de staging.
+- Isolar dados pessoais e credenciais de provedores de pagamento.

package/templates/ARCHITECTURE.md

@@ -0,0 +1,8 @@
+# Architecture — [projeto]
+## Contexto e limites
+## Componentes, responsabilidades e integrações
+## Diagrama (texto ou Mermaid)
+## Fluxos críticos e segurança
+## Modelo de dados (sem dados reais)
+## Decisões arquiteturais e trade-offs
+## Dívida técnica e plano futuro

package/templates/BASELINE.md

@@ -0,0 +1,16 @@
+# Baseline — [projeto]
+Status G2: [...] | Status G3: pendente
+## Comportamento esperado antes da alteração
+## Fluxos testados
+| Cenário | Ambiente | Comando/procedimento | Resultado | Evidência |
+|---|---|---|---|---|
+## Falhas já existentes
+## Lacunas de cobertura
+## Riscos de regressão
+## Decisão G3
+
+## Projeto novo sem aplicação
+Tipo: [pré-implementação / executável] | Referência preservada da baseline anterior: [...]
+Inventário e ferramentas realmente verificadas: [...]
+Testes indisponíveis sem bootstrap e motivo: [...]
+G3 aprova ponto de partida e lacunas; não aprova funcionalidades inexistentes. Bootstrap só após G4; baseline executável registrada em P06.

package/templates/CURRENT_STATE.md

@@ -0,0 +1,15 @@
+# Estado atual — [projeto]
+Atualizado em: [AAAA-MM-DD]
+## Trilha e fase atual
+## Stack e ambiente confirmado
+## Última task concluída / ativa
+## Funcionalidades verificadas
+## Mudanças locais não commitadas
+## Bloqueios e riscos
+## Aprovações pendentes (G0–G6)
+## Próximos passos em ordem
+## Referências de documentos / PRs
+
+## Modo de banco e aprovações canônicas
+Modo do projeto: MANUAL_SQL | Task e override humano (se houver): [...]
+IDs/revisões vigentes em DECISIONS, rejeições/revogações e revalidações pendentes: [...]

package/templates/DATABASE_CHANGE.md

@@ -0,0 +1,31 @@
+# TASK-XXX — Plano e controle de banco
+## Modo e evidências
+Modo do projeto: [MANUAL_SQL por padrão; herdar escolha humana vigente] | Modo da task: [...]
+DB_MODE (escolha/override humano): [...] | Executor: [...]
+Motor e versão real: [...] | Evidência sanitizada: [...]
+Ambiente/alvo: [...] | Schema, engine, charset/collation e SQL mode: [...]
+Se desconhecido, bloquear SQL executável dependente dessas informações. Para outro motor/interface, acordar dialeto e procedimento sem alterar o modo implicitamente.
+## Aprovações canônicas
+G2: [...] | G4: [...] | DB_CHANGE: [...] | DB_EXEC: [...] | G6 se produção: [...]
+Revisão/hash dos scripts: [...] | Janela/validade/repetições autorizadas: [...]
+G4 e escolha de modo não autorizam escrita. MANUAL_SQL permite apenas preparação pelo agente.
+## Artefatos por task
+Pasta: `docs/tasks/TASK-XXX/sql/` (sem dumps, credenciais ou dados reais).
+- `01-precheck.sql`: versão, schema, pré-condições e resultados esperados.
+- `02-change.sql`: mudança compatível com o motor/versão confirmados.
+- `03-postcheck.sql`: invariantes e resultados esperados.
+- `04-rollback.sql`: reversão segura quando possível; ausência justificada abaixo.
+- `README.md`: roteiro manual de phpMyAdmin e referências das aprovações.
+## Riscos e backup
+Locks, indisponibilidade, perda de dados, commits implícitos, repetição e dependências: [...]
+Backup necessário, responsável, referência segura e evidência de restauração validada: [...]
+## Execução manual no phpMyAdmin
+Humano autorizado confirma servidor/banco/versão, backup e aprovações; abre a aba SQL do banco correto, executa precheck e confere resultados; executa a mudança aprovada por etapas; executa postcheck e registra evidências sanitizadas. Não prosseguir se pré-condições falharem. Não repetir nem executar reversão sem conferir autorização específica.
+Adaptar a interface e etapas à instalação real. O agente não executa nem simula resultados.
+## Validação e condições de parada
+Critérios de sucesso/falha, observações e responsável: [...]
+## Reversão ou compensação
+Possibilidade técnica, limitações transacionais/DDL, perda irrecuperável e restauração: [...]
+Comandos de reversão exigem autorização própria de execução; nunca rollback automático.
+## Resultado real
+Não executado / executor / data / evidências / desvios / IDs de autorizações: [...]

package/templates/DECISIONS.md

@@ -0,0 +1,9 @@
+# Registro canônico de decisões e aprovações
+Única fonte de aprovações; tasks e estado referenciam IDs. Não registrar segredos. Preservar histórico por novos registros vinculados ao anterior.
+
+| ID | Data | Tipo/portão | Estado | Responsável humano / evidência da manifestação | Ação, escopo e ambiente/alvo | Executor | Artefato e revisão/hash | Restrições / validade | ID anterior / motivo |
+|---|---|---|---|---|---|---|---|---|---|
+
+Tipos: G0–G6, DB_MODE, DB_CHANGE, DB_EXEC ou ADR.
+Estados: pendente, aprovado, rejeitado, revogado, revalidação pendente.
+Rejeição/revogação bloqueia a ação; mudança relevante exige revalidação humana. Silêncio não é aprovação. A task não substitui DB_EXEC. Usar revisão documental identificável quando não houver commit. Para DB_EXEC registrar comandos/scripts, executor, alvo, janela e limite de repetições. O agente apenas transcreve manifestações humanas explícitas com evidência sanitizada.

package/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/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/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/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/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/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.