wizz-method 2.15.0 → 2.16.0

package/tools/hooks/wizz-feature.js

@@ -0,0 +1,401 @@
+// wizz-feature.js — CLI do ciclo de vida da feature ativa.
+//
+// Fonte de verdade: wizz-method/tools/hooks/. Instalada em `_wizz/hooks/` de
+// cada projeto (installer) e em `~/.claude/hooks/` (sync:global). Não é hook
+// registrado: é o passo VERIFICÁVEL que router, maestro e agentes de área
+// rodam, em vez de lembrar de editar o config à mão (foi o que falhou no
+// Spider: a regra "derive do pedido" dependia de memória do agente).
+//
+//   resolver                 feature ativa e de onde veio (branch > config > nada)
+//   definir <slug|texto>     grava active_feature e cria as subpastas (sem perguntar)
+//   artefato <tipo>          cria <tipo>-<slug>.md com frontmatter no lugar certo
+//   decidir "<texto>"        registra D-NN na spec da feature, na hora da decisão
+//   status <status>          rascunho|aprovado|implementado|no-ar na spec
+//   verificar                checklist de fechamento (exit 1 se houver pendência)
+//   encerrar                 status final na spec, limpa/troca active_feature
+//                            (recusa com pendência do checklist, salvo --forcar)
+//   listar                   features com pasta e o status de cada spec
+//
+// Opções: --json (saída para máquina), --cwd <dir>, --feature <slug>.
+// Fail-open: fora de projeto Wizz, avisa e sai com 0 sem escrever nada.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const lib = require('./wizz-feature-lib.js');
+
+const ALIASES = {
+  resolve: 'resolver',
+  set: 'definir',
+  artifact: 'artefato',
+  decide: 'decidir',
+  check: 'verificar',
+  close: 'encerrar',
+  list: 'listar',
+};
+
+function parseArgs(argv) {
+  const opts = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') opts.json = true;
+    else if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('--')) {
+        opts[key] = next;
+        i++;
+      } else opts[key] = true;
+    } else opts._.push(a);
+  }
+  return opts;
+}
+
+function rel(root, p) {
+  return path.relative(root, p) || '.';
+}
+
+/** Pasta de cada tipo de artefato, para uma feature. */
+function artifactPath(root, type, slug, dirs = lib.artifactDirs(root)) {
+  const where = lib.ARTIFACT_TYPES[type];
+  if (where === 'knowledge') return path.join(dirs.knowledge, `${type}-${slug}.md`);
+  return path.join(dirs[where], slug, `${type}-${slug}.md`);
+}
+
+function frontmatter(slug, type, status = 'rascunho') {
+  return ['---', `feature: ${slug}`, `tipo: ${type}`, `status: ${status}`, `atualizado_em: ${lib.today()}`, 'decisoes: []', '---', ''].join(
+    '\n',
+  );
+}
+
+const TEMPLATES = {
+  spec: (slug, title) =>
+    `${frontmatter(slug, 'spec')}
+# Spec · ${title}
+
+## Objetivo
+
+## Escopo
+
+## Critérios de aceite
+
+- [ ]
+
+## Decisões
+
+## Implementação
+
+<!-- Ao implementar: arquivos tocados, desvios da spec e testes que provam. -->
+`,
+  plano: (slug, title) => `${frontmatter(slug, 'plano')}\n# Plano · ${title}\n\n## Passos\n\n## Riscos\n`,
+  auditoria: (slug, title) => `${frontmatter(slug, 'auditoria')}\n# Auditoria · ${title}\n\n## Achados\n\n## Prioridades\n`,
+  story: (slug, title) => `${frontmatter(slug, 'story')}\n# Story · ${title}\n\n## Contexto\n\n## Critérios de aceite\n\n- [ ]\n`,
+  review: (slug, title) => `${frontmatter(slug, 'review')}\n# Review · ${title}\n\n## Achados\n\n## Veredito\n`,
+  roteiro: (slug, title) =>
+    `${frontmatter(slug, 'roteiro')}
+# Roteiro de aplicação · ${title}
+
+## Pré-requisitos
+
+## Passos
+
+## Verificação
+
+## Rollback
+`,
+};
+
+function titleOf(slug, explicit) {
+  if (typeof explicit === 'string' && explicit.trim()) return explicit.trim();
+  return slug.replaceAll('-', ' ').replace(/^./, (c) => c.toUpperCase());
+}
+
+/** Cria o artefato se não existir. Devolve {path, created}. */
+function ensureArtifact(root, type, slug, title) {
+  const file = artifactPath(root, type, slug);
+  if (fs.existsSync(file)) return { path: file, created: false };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, TEMPLATES[type](slug, titleOf(slug, title)));
+  return { path: file, created: true };
+}
+
+function touch(text) {
+  return lib.setFrontmatterField(text, 'atualizado_em', lib.today());
+}
+
+// ── comandos ────────────────────────────────────────────────────────────
+
+function cmdResolver(state) {
+  return {
+    ok: true,
+    data: { feature: state.slug, origem: state.source || 'nenhuma', branch: state.git.branch, config: state.fromConfig },
+    line: state.slug
+      ? `Feature ativa: ${state.slug} (${state.source === 'branch' ? 'do branch git' : 'do config'}).`
+      : 'Nenhuma feature ativa: o primeiro pedido nomeado define uma (`definir <slug>`).',
+  };
+}
+
+function cmdDefinir(state, opts) {
+  const raw = opts._.slice(1).join(' ');
+  const slug = lib.toSlug(raw);
+  if (!slug) return { ok: false, code: 2, line: 'Uso: definir <slug ou nome da feature>. Nada foi gravado.' };
+  const { root } = state;
+  const previous = state.fromConfig;
+  lib.writeConfigValue(root, 'active_feature', slug);
+  const dirs = lib.artifactDirs(root);
+  for (const d of [dirs.planning, dirs.implementation]) fs.mkdirSync(path.join(d, slug), { recursive: true });
+
+  const parts = [
+    `Feature: ${slug}. Artefatos em ${rel(root, path.join(dirs.planning, slug))}/ e ${rel(root, path.join(dirs.implementation, slug))}/.`,
+  ];
+  if (previous && previous !== slug) parts.push(`Troca: ${previous} → ${slug} (${previous} segue aberta até ser encerrada).`);
+  if (state.fromBranch && state.fromBranch !== slug)
+    parts.push(
+      `Atenção: o branch ${state.git.branch} aponta para ${state.fromBranch} e ganha do config. Troque de branch se ${slug} é outro trabalho.`,
+    );
+  const proposeBranch = state.git.isRepo && state.onTrunk && state.featureBranches === 'auto';
+  if (proposeBranch) parts.push(`Proposta (feature_branches: auto): git switch -c feat/${slug}`);
+  return {
+    ok: true,
+    data: { feature: slug, anterior: previous, branch_proposto: proposeBranch ? `feat/${slug}` : '' },
+    line: parts.join(' '),
+  };
+}
+
+function requireFeature(state, opts) {
+  const slug = lib.toSlug(typeof opts.feature === 'string' ? opts.feature : '') || state.slug;
+  return slug;
+}
+
+function cmdArtefato(state, opts) {
+  const type = (opts._[1] || '').toLowerCase();
+  if (!lib.ARTIFACT_TYPES[type]) return { ok: false, code: 2, line: `Tipo inválido. Use: ${Object.keys(lib.ARTIFACT_TYPES).join(', ')}.` };
+  const slug = requireFeature(state, opts);
+  if (!slug) return { ok: false, code: 2, line: 'Sem feature ativa: rode `definir <slug>` antes de criar artefato.' };
+  const { path: file, created } = ensureArtifact(state.root, type, slug, opts.titulo);
+  return {
+    ok: true,
+    data: { caminho: rel(state.root, file), criado: created },
+    line: `${created ? 'Criado' : 'Já existe'}: ${rel(state.root, file)}`,
+  };
+}
+
+function cmdDecidir(state, opts) {
+  const texto = opts._.slice(1).join(' ').trim();
+  if (!texto) return { ok: false, code: 2, line: 'Uso: decidir "<decisão do dono>".' };
+  const slug = requireFeature(state, opts);
+  if (!slug) return { ok: false, code: 2, line: 'Sem feature ativa: rode `definir <slug>` antes de registrar decisão.' };
+  const { path: file } = ensureArtifact(state.root, 'spec', slug);
+  let text = fs.readFileSync(file, 'utf8');
+  const ids = [...text.matchAll(/\bD-(\d+)\b/g)].map((m) => Number(m[1]));
+  const id = `D-${String((ids.length > 0 ? Math.max(...ids) : 0) + 1).padStart(2, '0')}`;
+  const entry = `- **${id}** (${lib.today()}): ${texto}`;
+
+  const lines = text.split('\n');
+  const head = lines.findIndex((l) => /^##\s+Decis(õ|o)es\s*$/i.test(l.trim()));
+  if (head === -1) {
+    text = `${text.replace(/\n*$/, '\n')}\n## Decisões\n\n${entry}\n`;
+  } else {
+    let end = head + 1;
+    while (end < lines.length && !/^#{1,2}\s/.test(lines[end])) end++;
+    while (end > head + 1 && lines[end - 1].trim() === '') end--;
+    const block = end === head + 1 ? ['', entry] : [entry];
+    text = [...lines.slice(0, end), ...block, ...lines.slice(end)].join('\n');
+  }
+  const current = lib.parseFrontmatter(text).data.decisoes || '[]';
+  const list = current
+    .replaceAll(/[[\]]/g, '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  text = touch(lib.setFrontmatterField(text, 'decisoes', `[${[...list, id].join(', ')}]`));
+  fs.writeFileSync(file, text);
+  return { ok: true, data: { id, caminho: rel(state.root, file) }, line: `${id} registrada em ${rel(state.root, file)}.` };
+}
+
+function setSpecStatus(state, slug, status) {
+  const { path: file } = ensureArtifact(state.root, 'spec', slug);
+  const text = fs.readFileSync(file, 'utf8');
+  fs.writeFileSync(file, touch(lib.setFrontmatterField(text, 'status', status)));
+  return file;
+}
+
+function cmdStatus(state, opts) {
+  const status = (opts._[1] || '').toLowerCase();
+  if (!lib.STATUS.includes(status)) return { ok: false, code: 2, line: `Status inválido. Use: ${lib.STATUS.join('|')}.` };
+  const slug = requireFeature(state, opts);
+  if (!slug) return { ok: false, code: 2, line: 'Sem feature ativa: rode `definir <slug>` primeiro.' };
+  const file = setSpecStatus(state, slug, status);
+  return { ok: true, data: { status, caminho: rel(state.root, file) }, line: `Status de ${slug}: ${status}.` };
+}
+
+/** Artefatos tipados soltos na raiz das pastas de artefato (fora de qualquer feature). */
+function looseArtifacts(root, dirs) {
+  const out = [];
+  for (const d of [dirs.planning, dirs.implementation]) {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(d, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) if (e.isFile() && lib.artifactTypeOf(e.name)) out.push(rel(root, path.join(d, e.name)));
+  }
+  return out;
+}
+
+/**
+ * Checklist de fechamento. Itens mecânicos são checados; os de julgamento
+ * (Cérebro, memória) voltam como "confirmar" para o agente responder.
+ */
+function checklist(state, slug, { statusOverride } = {}) {
+  const { root } = state;
+  const dirs = lib.artifactDirs(root);
+  const items = [];
+  const add = (ok, item, detalhe = '') => items.push({ ok, item, detalhe });
+
+  add(Boolean(slug), 'feature resolvida', slug || 'nenhuma feature ativa');
+  const soltos = looseArtifacts(root, dirs);
+  add(soltos.length === 0, 'artefatos no lugar', soltos.length > 0 ? `soltos: ${soltos.join(', ')}` : '');
+
+  if (slug) {
+    const spec = artifactPath(root, 'spec', slug, dirs);
+    const exists = fs.existsSync(spec);
+    add(exists, 'spec da feature existe', rel(root, spec));
+    if (exists) {
+      const text = fs.readFileSync(spec, 'utf8');
+      const problems = lib.frontmatterProblems(text, slug);
+      add(problems.length === 0, 'frontmatter da spec válido', problems.join('; '));
+      add(
+        Boolean(
+          lib
+            .sectionContent(text, 'Crit[ée]rios de aceite')
+            ?.replaceAll(/^- \[ \]\s*$/gm, '')
+            .trim(),
+        ),
+        'spec com critérios de aceite',
+      );
+      const status = statusOverride || lib.parseFrontmatter(text).data.status;
+      if (status === 'implementado' || status === 'no-ar')
+        add(Boolean(lib.sectionContent(text, 'Implementa[çc][ãa]o')), 'seção Implementação preenchida');
+      if (status === 'no-ar') {
+        const roteiro = artifactPath(root, 'roteiro', slug, dirs);
+        const ok = fs.existsSync(roteiro) && lib.sectionContent(fs.readFileSync(roteiro, 'utf8'), 'Rollback');
+        add(Boolean(ok), 'roteiro de aplicação com rollback', rel(root, roteiro));
+      }
+    }
+  }
+  const pendentes = items.filter((i) => !i.ok);
+  const confirmar = [
+    'Cérebro: bloco Estado do projeto atualizado + 1 linha na tabela Sessões',
+    'Auto-memória: só armadilha reproduzível ou preferência do dono (estado e decisão vão no Cérebro)',
+  ];
+  return { items, pendentes, confirmar };
+}
+
+function cmdVerificar(state, opts) {
+  const slug = requireFeature(state, opts);
+  const { items, pendentes, confirmar } = checklist(state, slug);
+  const lines = items.map((i) => `${i.ok ? '✓' : '✗'} ${i.item}${i.detalhe ? ` (${i.detalhe})` : ''}`);
+  lines.push(...confirmar.map((c) => `? confirmar: ${c}`));
+  return {
+    ok: pendentes.length === 0,
+    code: pendentes.length === 0 ? 0 : 1,
+    data: { feature: slug, itens: items, confirmar },
+    line: lines.join('\n'),
+  };
+}
+
+function cmdEncerrar(state, opts) {
+  const slug = requireFeature(state, opts);
+  if (!slug) return { ok: false, code: 2, line: 'Nenhuma feature ativa para encerrar.' };
+  const status = typeof opts.status === 'string' ? opts.status.toLowerCase() : 'no-ar';
+  if (!lib.STATUS.includes(status)) return { ok: false, code: 2, line: `Status inválido. Use: ${lib.STATUS.join('|')}.` };
+  // Não fecha com pendência: a checagem roda ANTES de gravar, já com o status final.
+  const pend = checklist(state, slug, { statusOverride: status }).pendentes;
+  if (pend.length > 0 && !opts.forcar) {
+    return {
+      ok: false,
+      code: 1,
+      data: { feature: slug, status, pendencias: pend.map((p) => p.item) },
+      line: `Não encerrei ${slug}: ${pend.map((p) => p.item + (p.detalhe ? ` (${p.detalhe})` : '')).join('; ')}. Resolva e rode de novo (ou --forcar se o dono aceitar a pendência).`,
+    };
+  }
+  const file = setSpecStatus(state, slug, status);
+  const next = lib.toSlug(typeof opts.proxima === 'string' ? opts.proxima : '');
+  if (state.fromConfig === slug || !state.fromConfig) lib.writeConfigValue(state.root, 'active_feature', next);
+  if (next) {
+    const dirs = lib.artifactDirs(state.root);
+    for (const d of [dirs.planning, dirs.implementation]) fs.mkdirSync(path.join(d, next), { recursive: true });
+  }
+  const parts = [`Feature ${slug} encerrada (${status}) em ${lib.today()}. Spec: ${rel(state.root, file)}.`];
+  parts.push(next ? `Feature ativa agora: ${next}.` : 'Nenhuma feature ativa agora.');
+  if (state.fromBranch === slug) parts.push(`O branch ${state.git.branch} ainda aponta para ${slug}: volte ao tronco ou troque de branch.`);
+  parts.push(`Registre no Cérebro: Estado do projeto + linha na tabela Sessões (${slug}: ${status} em ${lib.today()}).`);
+  if (pend.length > 0) parts.push(`Pendências: ${pend.map((p) => p.item).join('; ')}.`);
+  return { ok: true, data: { feature: slug, status, proxima: next, pendencias: pend.map((p) => p.item) }, line: parts.join(' ') };
+}
+
+function cmdListar(state) {
+  const dirs = lib.artifactDirs(state.root);
+  let names = [];
+  try {
+    names = fs
+      .readdirSync(dirs.planning, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name);
+  } catch {
+    // sem pasta de planejamento: nenhuma feature
+  }
+  const features = names.map((slug) => {
+    const spec = artifactPath(state.root, 'spec', slug, dirs);
+    const status = fs.existsSync(spec) ? lib.parseFrontmatter(fs.readFileSync(spec, 'utf8')).data.status || '?' : 'sem spec';
+    return { feature: slug, status, ativa: slug === state.slug };
+  });
+  const line =
+    features.length === 0
+      ? 'Nenhuma feature com pasta ainda.'
+      : features.map((f) => `${f.ativa ? '*' : ' '} ${f.feature} (${f.status})`).join('\n');
+  return { ok: true, data: { features }, line };
+}
+
+const COMMANDS = {
+  resolver: cmdResolver,
+  definir: cmdDefinir,
+  artefato: cmdArtefato,
+  decidir: cmdDecidir,
+  status: cmdStatus,
+  verificar: cmdVerificar,
+  encerrar: cmdEncerrar,
+  listar: cmdListar,
+};
+
+/**
+ * Roda um comando e devolve o resultado (sem escrever no stdout): é o que os
+ * testes e o eval chamam.
+ * @param {string[]} argv
+ * @returns {{ok: boolean, code?: number, data?: object, line: string}}
+ */
+function run(argv) {
+  const opts = parseArgs(argv);
+  const name = ALIASES[opts._[0]] || opts._[0];
+  const command = COMMANDS[name];
+  if (!command) return { ok: false, code: 2, line: `Comandos: ${Object.keys(COMMANDS).join(', ')}.` };
+  const cwd = typeof opts.cwd === 'string' ? path.resolve(opts.cwd) : process.cwd();
+  const state = lib.resolveFeature(cwd);
+  if (!state.isWizz) return { ok: true, code: 0, data: { wizz: false }, line: 'Não é projeto Wizz (sem _wizz/): nada a fazer.' };
+  try {
+    return command(state, opts);
+  } catch (error) {
+    return { ok: false, code: 1, line: `Falhou sem alterar o resto do projeto: ${error.message}` };
+  }
+}
+
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+  const result = run(argv);
+  const json = argv.includes('--json');
+  process.stdout.write(json ? `${JSON.stringify({ ok: result.ok, ...result.data, mensagem: result.line })}\n` : `${result.line}\n`);
+  process.exit(result.code ?? (result.ok ? 0 : 1));
+}
+
+module.exports = { run, checklist, artifactPath, TEMPLATES };

package/tools/hooks/wizz-layout-lib.js

@@ -0,0 +1,152 @@
+// wizz-layout-lib.js — o que pode ficar solto na raiz e para onde vai o resto.
+//
+// Fonte de verdade: wizz-method/tools/hooks/. Usado pelo hook
+// wizz-artifact-guard (sugere destino ao criar arquivo solto) e pela CLI
+// wizz-arrumar (propõe layout, monta o manifesto da arrumação).
+//
+// O layout mora em `_wizz/bmm/config.yaml`, bloco `layout:` (tipo → pasta).
+// Tipos canônicos: codigo, scripts, dados, docs, midia, arquivo. Um tipo com
+// pasta "." significa "esse tipo vive na raiz" (ex.: app Next.js na raiz).
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const LAYOUT_TYPES = {
+  codigo: 'código do produto (app, lib, componentes)',
+  scripts: 'scripts e utilitários soltos (.sh, .py, .mjs)',
+  dados: 'dados de entrada e saída (.csv, .json, planilhas, bancos locais)',
+  docs: 'documentação e anotações (.md, .pdf, .docx)',
+  midia: 'imagens, vídeos e áudios',
+  arquivo: 'o que saiu de uso mas não pode ser apagado (zip, backup, versões antigas)',
+};
+
+const DEFAULT_LAYOUT = { scripts: 'scripts', dados: 'dados', docs: 'docs', arquivo: 'arquivo' };
+
+// Arquivos que pertencem à raiz por convenção de ferramenta. Nunca viram aviso.
+const ROOT_ALLOWED = [
+  /^\./, // dotfiles (.gitignore, .env.example, .nvmrc...)
+  /^(readme|license|licence|changelog|contributing|security|code_of_conduct|notice|third-party-notices|authors)(\..+)?$/i,
+  /^(claude|agents|gemini|copilot-instructions)\.md$/i,
+  /^(package\.json|package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|pnpm-workspace\.yaml|yarn\.lock|bun\.lockb?|bunfig\.toml)$/i,
+  /^(ts|js)config(\..+)?\.json$/i,
+  /^[\w.-]+\.config\.(js|cjs|mjs|ts|cts|mts|json|yaml|yml|toml)$/i,
+  /^(next-env\.d\.ts|middleware\.(js|ts)|proxy\.(js|ts)|instrumentation(-client)?\.(js|ts))$/i,
+  /^(vercel\.json|vercel\.ts|netlify\.toml|fly\.toml|render\.yaml|railway\.json|app\.json|wrangler\.(toml|jsonc?))$/i,
+  /^(dockerfile.*|docker-compose.*\.ya?ml|compose\.ya?ml|makefile|procfile|justfile|taskfile\.ya?ml)$/i,
+  /^(requirements.*\.txt|pyproject\.toml|setup\.(py|cfg)|pipfile(\.lock)?|poetry\.lock|uv\.lock|\.python-version|manage\.py)$/i,
+  /^(go\.(mod|sum|work)|cargo\.(toml|lock)|gemfile(\.lock)?|rakefile|deno\.jsonc?|deno\.lock|composer\.(json|lock))$/i,
+  /^(biome\.jsonc?|turbo\.json|nx\.json|lerna\.json|renovate\.json|components\.json|skills-lock\.json|tsconfig\.tsbuildinfo)$/i,
+];
+
+const EXT_TYPE = {
+  scripts: ['.sh', '.bash', '.zsh', '.ps1', '.py', '.mjs', '.cjs', '.js', '.ts', '.rb', '.pl', '.php', '.ipynb'],
+  dados: ['.csv', '.tsv', '.json', '.jsonl', '.ndjson', '.xlsx', '.xls', '.ods', '.parquet', '.sqlite', '.sqlite3', '.db', '.sql', '.xml'],
+  docs: ['.md', '.mdx', '.pdf', '.docx', '.doc', '.txt', '.rtf', '.odt', '.pptx', '.key', '.html', '.htm'],
+  midia: ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.heic', '.mp4', '.mov', '.webm', '.mp3', '.wav', '.m4a'],
+  arquivo: ['.zip', '.tar', '.gz', '.tgz', '.7z', '.rar', '.bak', '.old', '.orig', '.log', '.tmp'],
+};
+
+// Tipo de reserva quando o layout não tem o tipo natural do arquivo.
+const FALLBACK = { midia: 'docs', scripts: 'codigo', dados: 'arquivo', docs: 'arquivo' };
+
+/** Tipo natural de um arquivo pela extensão, ou ''. */
+function typeOfFile(fileName) {
+  const ext = path.extname(fileName).toLowerCase();
+  for (const [type, exts] of Object.entries(EXT_TYPE)) if (exts.includes(ext)) return type;
+  return '';
+}
+
+function normalizeDir(dir) {
+  const d = String(dir || '')
+    .trim()
+    .replace(/^\.\//, '')
+    .replace(/\/+$/, '');
+  return d === '' ? '.' : d;
+}
+
+/** Arquivos extras liberados na raiz via `layout.raiz_extra: "a.txt, b.md"`. */
+function extraAllowed(layout) {
+  return String(layout.raiz_extra || '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Pode ficar na raiz? Convenção de ferramenta, lista extra, ou o tipo do
+ * arquivo vive na raiz por decisão do layout (pasta ".").
+ * @param {string} fileName
+ * @param {Record<string,string>} layout
+ */
+function isAllowedAtRoot(fileName, layout = {}) {
+  if (ROOT_ALLOWED.some((re) => re.test(fileName))) return true;
+  if (extraAllowed(layout).includes(fileName)) return true;
+  const type = typeOfFile(fileName);
+  if (type && normalizeDir(layout[type]) === '.' && layout[type] !== undefined) return true;
+  // Código na raiz é decisão do layout (codigo: "."), não acidente.
+  return type === 'scripts' && layout.codigo !== undefined && normalizeDir(layout.codigo) === '.';
+}
+
+/**
+ * Pasta de destino sugerida para um arquivo solto na raiz.
+ * @returns {{type: string, dir: string}|null} null quando não há sugestão
+ */
+function suggestDestination(fileName, layout = {}) {
+  const natural = typeOfFile(fileName);
+  if (!natural) return null;
+  const candidates = [natural, FALLBACK[natural]].filter(Boolean);
+  for (const type of candidates) {
+    if (layout[type] !== undefined && normalizeDir(layout[type]) !== '.') return { type, dir: normalizeDir(layout[type]) };
+  }
+  return null;
+}
+
+/**
+ * Propõe um layout olhando o que já existe: reaproveita pastas com o nome de
+ * um tipo (ou sinônimo) e só sugere criar as que os arquivos soltos pedem.
+ * @param {string} root
+ * @returns {{layout: Record<string,string>, loose: string[]}}
+ */
+function proposeLayout(root) {
+  const SYNONYMS = {
+    codigo: ['src', 'app', 'apps', 'packages', 'lib'],
+    scripts: ['scripts', 'bin', 'tools'],
+    dados: ['dados', 'data', 'datasets'],
+    docs: ['docs', 'doc', 'documentacao'],
+    midia: ['midia', 'media', 'assets'],
+    arquivo: ['arquivo', 'archive', 'old', 'backups'],
+  };
+  let entries = [];
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return { layout: { ...DEFAULT_LAYOUT }, loose: [] };
+  }
+  const dirs = new Set(entries.filter((e) => e.isDirectory()).map((e) => e.name));
+  const loose = entries.filter((e) => e.isFile() && !isAllowedAtRoot(e.name, {})).map((e) => e.name);
+  const layout = {};
+  for (const [type, names] of Object.entries(SYNONYMS)) {
+    const found = names.find((n) => dirs.has(n));
+    if (found) layout[type] = found;
+  }
+  // Projeto JS com app na raiz (package.json + app/ ou src/): código vive na raiz.
+  if (entries.some((e) => e.name === 'package.json') && layout.codigo) layout.codigo = '.';
+  for (const name of loose) {
+    const type = typeOfFile(name);
+    if (type && !layout[type]) layout[type] = DEFAULT_LAYOUT[type] || type;
+  }
+  for (const [type, dir] of Object.entries(DEFAULT_LAYOUT)) if (!layout[type]) layout[type] = dir;
+  return { layout, loose };
+}
+
+module.exports = {
+  LAYOUT_TYPES,
+  DEFAULT_LAYOUT,
+  ROOT_ALLOWED,
+  EXT_TYPE,
+  typeOfFile,
+  normalizeDir,
+  isAllowedAtRoot,
+  suggestDestination,
+  proposeLayout,
+};

package/tools/hooks/wizz-router-enforce.js

@@ -138,6 +138,25 @@ function buildContext(isWizzProject) {
   );
 }
 
+// Linha de feature, por prompt, em projeto Wizz (2026-10-02, caso Spider).
+// O SessionStart avisa 1x, mas é aqui que o pedido nomeado chega: sem este
+// lembrete o despacho saía sem feature e o artefato caía na raiz. Fail-open:
+// lib ausente ou erro = linha vazia, o roteamento segue igual.
+function featureLine(wizzRoot) {
+  if (!wizzRoot) return '';
+  try {
+    const lib = require('./wizz-feature-lib.js');
+    const state = lib.resolveFeature(wizzRoot);
+    const cmd = 'node _wizz/hooks/wizz-feature.js';
+    if (!state.slug) {
+      return ` Feature: nenhuma ativa. Pedido nomeado → ANTES de despachar \`${cmd} definir <slug do pedido>\` (sem perguntar); handoff leva \`feature:\`.`;
+    }
+    return ` Feature: ${state.slug}. Outro assunto → \`${cmd} definir <novo>\`; continuação mantém; entrega fechada → \`${cmd} encerrar\`. Handoff leva \`feature: ${state.slug}\`.`;
+  } catch {
+    return '';
+  }
+}
+
 function isTraceEnabled() {
   return process.env.WIZZ_TRACE === '1';
 }
@@ -216,7 +235,7 @@ function runHook() {
       const cwd = data.cwd || process.cwd();
       const wizzRoot = findWizzRoot(cwd);
       const isWizzProject = Boolean(wizzRoot);
-      const context = buildContext(isWizzProject);
+      const context = buildContext(isWizzProject) + featureLine(wizzRoot);
 
       const warnings = checkFallbackWarnings(isWizzProject, wizzRoot);
       if (warnings.length > 0) emitFallbackWarnings(warnings);
@@ -249,6 +268,7 @@ if (require.main === module) {
   module.exports = {
     isTrivial,
     buildContext,
+    featureLine,
     findWizzRoot,
     isTraceEnabled,
     getTraceFile,

package/tools/installer/core/doctor.js

@@ -21,7 +21,7 @@
 // — os testes rodam sem rtk/jq/python instalados e sem rede.
 
 const path = require('node:path');
-const { HOOK_DEFS, isOurHookCommand } = require('./hooks-settings');
+const { HOOK_DEFS, SUPPORT_FILES, isOurHookCommand } = require('./hooks-settings');
 const { classifyPython, PYTHON_ONLY_SKILLS } = require('./python-check');
 
 // Piso de versão do rtk que o hook rtk-rewrite.sh exige para `rtk rewrite`
@@ -169,6 +169,10 @@ function checkHooks({ wizzDir, settingsFile, globalSettingsFile, fileExists, rea
     }
   }
 
+  for (const id of SUPPORT_FILES) {
+    if (!fileExists(path.join(hooksDir, id))) missingFiles.push(id);
+  }
+
   if (missingFiles.length > 0) {
     return {
       check: 'hooks',

package/tools/installer/core/hooks-settings.js

@@ -30,8 +30,17 @@ const HOOK_DEFS = [
   // `rtkOnPath` é true — ver buildHookEntries abaixo.
   { id: 'rtk-rewrite.sh', event: 'PreToolUse', matcher: 'Bash', kind: 'shell', requires: 'rtk' },
   { id: 'wizz-decision-trace.js', event: 'Stop', kind: 'node' },
+  // Avisa artefato fora da pasta da feature e arquivo solto na raiz (2026-10-02).
+  // Nunca bloqueia: PostToolUse só devolve contexto para o agente corrigir.
+  { id: 'wizz-artifact-guard.js', event: 'PostToolUse', matcher: 'Write', kind: 'node' },
 ];
 
+// Arquivos de apoio copiados junto com os hooks, mas NUNCA registrados em
+// settings.json: bibliotecas que os hooks importam e as CLIs que os agentes
+// rodam (`node _wizz/hooks/wizz-feature.js definir <slug>`). Sem eles a
+// organização automática cala em silêncio (fail-open), então o doctor cobra.
+const SUPPORT_FILES = ['wizz-feature-lib.js', 'wizz-layout-lib.js', 'wizz-feature.js', 'wizz-arrumar.js'];
+
 const DEFAULT_TIMEOUT = 5;
 
 function commandFor(def) {
@@ -169,6 +178,7 @@ function mergeHooksIntoSettings(existingSettings, hookEntries) {
 }
 
 module.exports = {
+  SUPPORT_FILES,
   HOOKS_DIR,
   HOOK_DEFS,
   buildHookEntries,