wizz-method 2.15.0 → 2.16.0

package/tools/hooks/session-rules.js

@@ -11,8 +11,11 @@
 //   2. Feature ativa: resolve o `active_feature` SOZINHO, sem o usuário
 //      precisar invocar `wizz-set-feature` e responder duas perguntas. Ordem:
 //      branch git (mais fresco que o config) > `_wizz/bmm/config.yaml` > nada.
-//      Custo zero quando não há `_wizz/` nem branch de feature: a linha
-//      simplesmente não é emitida.
+//      Custo zero fora de projeto Wizz sem branch de feature: a linha
+//      simplesmente não é emitida. DENTRO de projeto Wizz sem feature sai um
+//      lembrete curto ("o primeiro pedido nomeado define uma", 2026-10-02):
+//      sem ele, projeto sem git ou na main ficava a vida toda sem feature
+//      (caso Spider). Mesmo lembrete para layout de pastas ausente.
 //
 //   3. Teto da auto-memória: o teto de 40 memórias e 8 KB de índice está
 //      escrito no CLAUDE.md global desde 2026-08-28, mas nada disparava a
@@ -39,163 +42,85 @@ const RULES =
   'concise communication by default, expand only on request; ' +
   'reply to the user in the language chosen at install (communication_language).';
 
-// Branches que NUNCA viram feature: são linha principal, não trabalho nomeado.
-const TRUNK = new Set(['main', 'master', 'develop', 'dev', 'staging', 'stage', 'prod', 'production', 'trunk', 'default', 'release']);
-
-// Branch de release/versão não é feature: nomeia um corte do produto, não um trabalho.
-const RELEASE_PREFIX = /^(release|rc|v)[/-]/i;
-
-// Prefixos de convenção que descrevem o TIPO do trabalho, não a feature.
-const TYPE_PREFIX = /^(feat|feature|fix|bugfix|hotfix|chore|refactor|docs|test|perf|ci|build|style)[/-]/i;
-
-/**
- * Normaliza um texto livre para o mesmo slug kebab-case que a skill
- * `wizz-set-feature` grava, para branch e config nunca divergirem por formato.
- * @param {string} raw
- * @returns {string} slug kebab-case, ou '' se não sobrar nada utilizável
- */
-function toSlug(raw) {
-  if (typeof raw !== 'string') return '';
-  return raw
-    .normalize('NFD')
-    .replaceAll(/[\u0300-\u036F]/g, '')
-    .toLowerCase()
-    .replaceAll(/[^a-z0-9]+/g, '-')
-    .replaceAll(/^-+|-+$/g, '')
-    .slice(0, 60);
+// Feature, git e config moram em wizz-feature-lib.js (mesma pasta: o installer
+// e o sync:global copiam tools/hooks/ inteiro). Se a lib faltar numa cópia
+// manual parcial, a regra de comunicação continua saindo e a feature cala.
+let lib = null;
+try {
+  lib = require('./wizz-feature-lib.js');
+} catch {
+  lib = null;
 }
 
-/**
- * Lê o branch atual sem subprocesso: `.git/HEAD` já traz o ref, e um read de
- * arquivo é mais barato e mais seguro que um `git` no PATH (que pode nem existir).
- * Sobe até 6 níveis para achar o `.git` de um subdiretório do repo.
- * @param {string} cwd
- * @returns {string} nome do branch, ou '' (detached HEAD, sem repo, erro)
- */
-function readGitBranch(cwd) {
-  let dir = cwd;
-  for (let i = 0; i < 6; i++) {
-    const gitPath = path.join(dir, '.git');
-    try {
-      const stat = fs.statSync(gitPath);
-      let headFile = path.join(gitPath, 'HEAD');
-      if (stat.isFile()) {
-        // worktree/submódulo: `.git` é um arquivo `gitdir: <caminho>`
-        const m = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(gitPath, 'utf8'));
-        if (!m) return '';
-        const resolved = path.resolve(dir, m[1].trim());
-        headFile = path.join(resolved, 'HEAD');
-      }
-      const head = fs.readFileSync(headFile, 'utf8').trim();
-      const ref = /^ref:\s*refs\/heads\/(.+)$/.exec(head);
-      return ref ? ref[1] : ''; // detached HEAD => sem branch => sem feature
-    } catch {
-      // segue subindo
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return '';
-}
+const HOOK_CMD = 'node _wizz/hooks/wizz-feature.js';
 
-/**
- * Deriva um slug de feature do nome do branch. Branch de tronco e branch sem
- * nome útil devolvem '' (nenhuma feature), nunca um slug inventado.
- * @param {string} branch
- * @returns {string}
- */
-function featureFromBranch(branch) {
-  if (!branch) return '';
-  if (TRUNK.has(branch.toLowerCase())) return '';
-  if (RELEASE_PREFIX.test(branch)) return '';
-  const stripped = branch.replace(TYPE_PREFIX, '');
-  const slug = toSlug(stripped);
-  if (!slug || TRUNK.has(slug)) return '';
-  // Branch que é só um número de issue não descreve feature nenhuma.
-  if (/^\d+$/.test(slug)) return '';
-  return slug;
-}
+const toSlug = (raw) => (lib ? lib.toSlug(raw) : '');
+const readGitBranch = (cwd) => (lib ? lib.readGitBranch(cwd) : '');
+const featureFromBranch = (branch) => (lib ? lib.featureFromBranch(branch) : '');
+const readConfigFeature = (root) => (lib ? lib.readConfigFeature(root) : { slug: '', configPath: '' });
+const findWizzRoot = (cwd) => (lib ? lib.findWizzRoot(cwd) : '');
 
 /**
- * Lê `active_feature` do config do módulo bmm. Parser de 1 chave de propósito:
- * o hook não pode depender de uma lib de YAML (roda fora do node_modules do repo).
- * @param {string} cwd
- * @returns {{slug: string, configPath: string}} slug '' quando ausente/vazio
+ * Lembretes de projeto Wizz que valem mesmo sem feature: nenhuma feature
+ * ativa (o primeiro pedido nomeado define uma), layout de pastas ausente e
+ * proposta de branch quando `feature_branches: auto`.
+ * @param {ReturnType<typeof lib.resolveFeature>} state
+ * @returns {string[]}
  */
-function readConfigFeature(cwd) {
-  const configPath = path.join(cwd, '_wizz', 'bmm', 'config.yaml');
-  try {
-    const text = fs.readFileSync(configPath, 'utf8');
-    const m = /^active_feature:\s*(.*)$/m.exec(text);
-    if (!m) return { slug: '', configPath };
-    const value = m[1]
-      .replace(/#.*$/, '')
-      .trim()
-      .replaceAll(/^["']|["']$/g, '');
-    return { slug: toSlug(value), configPath };
-  } catch {
-    return { slug: '', configPath };
+function wizzReminders(state) {
+  const out = [];
+  if (!state.slug) {
+    out.push(
+      `NENHUMA FEATURE ATIVA: o primeiro pedido nomeado (feature, lote, tela, bug com escopo) define uma. ` +
+        `Antes de despachar, derive o slug do pedido e grave: ${HOOK_CMD} definir <slug>. Sem perguntar; uma linha de confirmação.`,
+    );
+  } else if (state.featureBranches === 'auto' && state.git.isRepo && state.onTrunk) {
+    out.push(
+      `feature_branches: auto e você está em ${state.git.branch || 'HEAD solto'}: proponha em UMA linha \`git switch -c feat/${state.slug}\`.`,
+    );
   }
-}
-
-/**
- * Acha a raiz do projeto Wizz (a pasta que contém `_wizz/`) subindo do cwd.
- * O agente costuma rodar de uma subpasta, então checar só o cwd erraria.
- * @param {string} cwd
- * @returns {string} caminho da raiz, ou '' se não for projeto Wizz
- */
-function findWizzRoot(cwd) {
-  let dir = cwd;
-  for (let i = 0; i < 6; i++) {
-    try {
-      if (fs.existsSync(path.join(dir, '_wizz'))) return dir;
-    } catch {
-      // ignora e segue subindo
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
+  if (!state.hasLayout) {
+    out.push(
+      'PROJETO SEM LAYOUT DE PASTAS: no primeiro pedido, proponha a estrutura por tipo em UMA linha ' +
+        '(node _wizz/hooks/wizz-arrumar.js layout) e grave com `layout --gravar`. Arquivo novo nunca nasce solto na raiz.',
+    );
   }
-  return '';
+  return out;
 }
 
 /**
- * Monta a linha de contexto da feature. Devolve '' quando não há feature
- * nenhuma. Silêncio custa zero token e é o caso comum fora de projeto Wizz.
+ * Monta o contexto de feature. Fora de projeto Wizz e sem branch de feature
+ * devolve '' (silêncio custa zero token). Em projeto Wizz sem feature, sai o
+ * lembrete curto: é o que faz a organização acontecer sem o dono pedir.
  * @param {string} cwd
  * @returns {string}
  */
 function buildFeatureContext(cwd) {
-  const wizzRoot = findWizzRoot(cwd);
-  const isWizzProject = Boolean(wizzRoot);
-  const fromConfig = isWizzProject ? readConfigFeature(wizzRoot) : { slug: '', configPath: '' };
-  const fromBranch = featureFromBranch(readGitBranch(cwd));
-
-  // O branch ganha do config: é o que descreve o trabalho de AGORA. O config
-  // pode ter ficado numa feature antiga que ninguém lembrou de trocar.
-  const active = fromBranch || fromConfig.slug;
-  if (!active) return '';
+  if (!lib) return '';
+  const state = lib.resolveFeature(cwd);
+  const fromBranch = state.isWizz ? state.fromBranch : featureFromBranch(readGitBranch(cwd));
+  const active = state.isWizz ? state.slug : fromBranch;
+  const parts = [];
 
-  const parts = [
-    `FEATURE ATIVA: ${active}` + (fromBranch ? ' (derivada do branch git).' : ' (do config).'),
-    'Use como contexto sem perguntar nada:',
-    isWizzProject
-      ? `artefatos de planejamento e implementação vão para as subpastas ${active}/;`
-      : 'não é projeto Wizz, então não há subpasta de artefato;',
-    `memória gravada nesta sessão leva tema/feature "${active}".`,
-  ];
-
-  if (fromBranch && isWizzProject && fromConfig.slug !== fromBranch) {
+  if (active) {
+    parts.push(
+      `FEATURE ATIVA: ${active}` + (fromBranch ? ' (derivada do branch git).' : ' (do config).'),
+      'Use como contexto sem perguntar nada:',
+      state.isWizz
+        ? `artefatos de planejamento e implementação vão para as subpastas ${active}/ com nome <tipo>-<slug>.md (${HOOK_CMD} artefato <tipo>);`
+        : 'não é projeto Wizz, então não há subpasta de artefato;',
+      `memória gravada nesta sessão leva tema/feature "${active}".`,
+    );
+    if (fromBranch && state.isWizz && state.fromConfig !== fromBranch) {
+      parts.push(
+        `O config (_wizz/bmm/config.yaml) ainda diz "${state.fromConfig || 'vazio'}": grave "${active}" nele (${HOOK_CMD} definir ${active}) e avise em UMA linha.`,
+      );
+    }
     parts.push(
-      `O config (_wizz/bmm/config.yaml) ainda diz "${fromConfig.slug || 'vazio'}": grave "${active}" nele na primeira vez que escrever um artefato, e avise em UMA linha.`,
+      'NÃO peça confirmação de feature. Pedido de OUTRO assunto troca a feature (definir <novo>); continuação mantém. Pergunte só se houver ambiguidade real entre duas features abertas.',
     );
   }
-
-  parts.push(
-    'NÃO peça confirmação de feature. Só invoque a skill wizz-set-feature se o usuário pedir explicitamente para trocar, ou se houver ambiguidade real entre duas features abertas.',
-  );
-
+  if (state.isWizz) parts.push(...wizzReminders(state));
   return parts.join(' ');
 }
 

package/tools/hooks/wizz-arrumar.js

@@ -0,0 +1,418 @@
+// wizz-arrumar.js — arrumação da raiz do projeto com manifesto e desfazer.
+//
+// Fonte de verdade: wizz-method/tools/hooks/. Instalada em `_wizz/hooks/`.
+// É o padrão que deu certo no Spider (2026-10-02), agora repetível:
+// manifesto .tsv revisável, script de desfazer, referências atualizadas em
+// código/docs/memórias e testes rodando antes e depois. Diferença do Spider:
+// o desfazer também restaura os arquivos cujas referências foram reescritas
+// (lá o desfazer só revertia os moves e avisava que o resto ficava torto).
+//
+//   layout                   propõe o layout de pastas (só mostra)
+//   layout --gravar [t=dir]  grava `layout:` no config, cria pastas + README curto
+//   planejar                 monta o manifesto dos arquivos soltos (não move nada)
+//   aplicar <manifesto.tsv>  move, atualiza referências, gera desfazer, roda testes
+//   mover <origem> <destino> atalho de um arquivo (manifesto de uma linha + aplicar)
+//   desfazer <pasta-da-arrumacao>
+//
+// Opções de aplicar/mover: --testes "<comando>", --refs <dir,dir> (ex.: pasta
+// da auto-memória), --manter (não desfaz sozinho se os testes quebrarem).
+// Cada execução fica em `<arquivo>/arrumacao/<data>-<hora>/`.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const lib = require('./wizz-feature-lib.js');
+const layoutLib = require('./wizz-layout-lib.js');
+
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  '.next',
+  '.nuxt',
+  '.svelte-kit',
+  'dist',
+  'build',
+  'out',
+  'coverage',
+  '_wizz',
+  '.venv',
+  'venv',
+  '__pycache__',
+  '.turbo',
+  '.vercel',
+  '.cache',
+]);
+const TEXT_EXT = new Set([
+  '.md',
+  '.mdx',
+  '.txt',
+  '.js',
+  '.cjs',
+  '.mjs',
+  '.ts',
+  '.tsx',
+  '.jsx',
+  '.py',
+  '.sh',
+  '.bash',
+  '.zsh',
+  '.json',
+  '.yaml',
+  '.yml',
+  '.toml',
+  '.html',
+  '.css',
+  '.sql',
+  '.ini',
+  '.cfg',
+  '.env.example',
+]);
+const MAX_TEXT_BYTES = 1024 * 1024;
+
+function parseArgs(argv) {
+  const opts = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    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 stamp() {
+  const d = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${lib.today()}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+}
+
+function archiveDir(root, layout) {
+  const dir = layout.arquivo && layoutLib.normalizeDir(layout.arquivo) !== '.' ? layoutLib.normalizeDir(layout.arquivo) : 'arquivo';
+  return path.join(root, dir, 'arrumacao');
+}
+
+function isInside(child, parent) {
+  const r = path.relative(parent, child);
+  return r !== '' && !r.startsWith('..') && !path.isAbsolute(r);
+}
+
+// ── layout ──────────────────────────────────────────────────────────────
+
+const README_BODY = (type, dir) =>
+  `# ${dir}\n\nPasta de ${layoutLib.LAYOUT_TYPES[type] || type}.\n\nDefinida em \`_wizz/bmm/config.yaml\` (bloco \`layout:\`). Arquivo novo deste tipo nasce aqui, nunca solto na raiz.\n`;
+
+function cmdLayout(root, opts) {
+  const config = lib.readConfig(root);
+  const { layout: proposed, loose } = layoutLib.proposeLayout(root);
+  if (!opts.gravar) {
+    const current = Object.keys(config.layout).length > 0 ? config.layout : null;
+    const shown = current || proposed;
+    const pairs = Object.entries(shown)
+      .map(([t, d]) => `${t}=${d}`)
+      .join(' ');
+    return {
+      ok: true,
+      line: current
+        ? `Layout atual: ${pairs}.`
+        : `Proposta de layout: ${pairs}. ${loose.length} arquivo(s) solto(s) na raiz. Grave com: layout --gravar ${pairs}`,
+    };
+  }
+  const given = opts._.slice(1).filter((a) => a.includes('='));
+  const layout = given.length > 0 ? Object.fromEntries(given.map((a) => a.split('=').map((s) => s.trim()))) : proposed;
+  lib.writeLayout(root, layout);
+  const created = [];
+  for (const [type, dir] of Object.entries(layout)) {
+    if (type === 'raiz_extra' || layoutLib.normalizeDir(dir) === '.') continue;
+    const abs = path.join(root, layoutLib.normalizeDir(dir));
+    if (!isInside(abs, root)) continue;
+    fs.mkdirSync(abs, { recursive: true });
+    const readme = path.join(abs, 'README.md');
+    if (!fs.existsSync(readme)) {
+      fs.writeFileSync(readme, README_BODY(type, layoutLib.normalizeDir(dir)));
+      created.push(layoutLib.normalizeDir(dir));
+    }
+  }
+  return {
+    ok: true,
+    line: `Layout gravado em _wizz/bmm/config.yaml: ${Object.entries(layout)
+      .map(([t, d]) => `${t}=${d}`)
+      .join(' ')}.${created.length > 0 ? ` README curto criado em: ${created.join(', ')}.` : ''}`,
+  };
+}
+
+// ── manifesto ───────────────────────────────────────────────────────────
+
+function readManifest(file) {
+  const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/).filter(Boolean);
+  return lines
+    .slice(lines[0] && lines[0].startsWith('origem\t') ? 1 : 0)
+    .map((l) => l.split('\t'))
+    .filter((cols) => cols.length >= 2 && cols[0] && cols[1])
+    .map(([origem, destino]) => ({ origem, destino }));
+}
+
+function writeManifest(file, moves) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, ['origem\tdestino', ...moves.map((m) => `${m.origem}\t${m.destino}`)].join('\n') + '\n');
+}
+
+function planMoves(root, layout) {
+  const moves = [];
+  const semDestino = [];
+  for (const e of fs.readdirSync(root, { withFileTypes: true })) {
+    if (!e.isFile() || layoutLib.isAllowedAtRoot(e.name, layout)) continue;
+    const dest = layoutLib.suggestDestination(e.name, layout);
+    if (dest) moves.push({ origem: e.name, destino: `${dest.dir}/${e.name}` });
+    else semDestino.push(e.name);
+  }
+  return { moves, semDestino };
+}
+
+function cmdPlanejar(root, opts) {
+  const config = lib.readConfig(root);
+  if (Object.keys(config.layout).length === 0) return { ok: false, code: 2, line: 'Sem layout no config: rode `layout --gravar` antes.' };
+  const { moves, semDestino } = planMoves(root, config.layout);
+  if (moves.length === 0)
+    return { ok: true, line: `Raiz já está arrumada.${semDestino.length > 0 ? ` Sem destino: ${semDestino.join(', ')}.` : ''}` };
+  const file =
+    typeof opts.saida === 'string' ? path.resolve(root, opts.saida) : path.join(archiveDir(root, config.layout), `plano-${stamp()}.tsv`);
+  writeManifest(file, moves);
+  return {
+    ok: true,
+    line:
+      `Manifesto com ${moves.length} move(s): ${path.relative(root, file)}. Revise e rode: aplicar ${path.relative(root, file)}` +
+      (semDestino.length > 0 ? `. Sem destino sugerido: ${semDestino.join(', ')}.` : '.'),
+  };
+}
+
+// ── referências ─────────────────────────────────────────────────────────
+
+function* walkText(dir, skipAbs) {
+  let entries = [];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const abs = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (SKIP_DIRS.has(e.name) || skipAbs.some((s) => abs === s || isInside(abs, s))) continue;
+      yield* walkText(abs, skipAbs);
+    } else if (e.isFile()) {
+      const ext = e.name.endsWith('.env.example') ? '.env.example' : path.extname(e.name).toLowerCase();
+      if (!TEXT_EXT.has(ext)) continue;
+      try {
+        if (fs.statSync(abs).size <= MAX_TEXT_BYTES) yield abs;
+      } catch {
+        // some no meio do caminho: ignora
+      }
+    }
+  }
+}
+
+function escapeRe(s) {
+  return s.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+}
+
+/**
+ * Reescreve referências a `origem` (caminho relativo à raiz) para `destino`.
+ * Casa `origem` e `./origem` quando não colado a outro caminho; não toca um
+ * arquivo cuja pasta tem um irmão com o mesmo nome (a referência é local).
+ */
+function rewriteRefs(text, moves, fileDir) {
+  let next = text;
+  for (const { origem, destino } of moves) {
+    if (fs.existsSync(path.join(fileDir, path.basename(origem))) && fileDir !== '') continue;
+    const re = new RegExp(String.raw`(?<![\w/.-])(\./)?${escapeRe(origem)}(?![\w-])`, 'g');
+    next = next.replace(re, (_m, dot) => `${dot || ''}${destino}`);
+  }
+  return next;
+}
+
+// ── aplicar / desfazer ──────────────────────────────────────────────────
+
+function runTests(root, cmd) {
+  if (!cmd || cmd === true) return null;
+  const r = spawnSync(cmd, { cwd: root, shell: true, encoding: 'utf8', timeout: 10 * 60 * 1000 });
+  return { ok: r.status === 0, code: r.status, tail: `${r.stdout || ''}${r.stderr || ''}`.trim().split('\n').slice(-5).join('\n') };
+}
+
+function shQuote(s) {
+  return `'${String(s).replaceAll("'", String.raw`'\''`)}'`;
+}
+
+function writeUndoScript(runDir, root, moves, edits) {
+  const lines = [
+    '#!/usr/bin/env bash',
+    `# Desfaz a arrumação de ${path.basename(runDir)}: restaura os arquivos editados e devolve os moves.`,
+    'set -euo pipefail',
+    `cd ${shQuote(root)}`,
+    ...edits.map((e) => `cp -p ${shQuote(path.join(runDir, e.backup))} ${shQuote(e.original)}`),
+    ...moves
+      .toReversed()
+      .map((m) => `[[ -e ${shQuote(m.destino)} && ! -e ${shQuote(m.origem)} ]] && mv ${shQuote(m.destino)} ${shQuote(m.origem)}`),
+    'echo "Arrumação desfeita."',
+    '',
+  ];
+  const file = path.join(runDir, 'desfazer.sh');
+  fs.writeFileSync(file, lines.join('\n'));
+  fs.chmodSync(file, 0o755);
+  return file;
+}
+
+function undo(root, runDir) {
+  const moves = readManifest(path.join(runDir, 'manifesto.tsv'));
+  const editsFile = path.join(runDir, 'edicoes.tsv');
+  const edits = fs.existsSync(editsFile)
+    ? fs
+        .readFileSync(editsFile, 'utf8')
+        .split('\n')
+        .filter(Boolean)
+        .map((l) => {
+          const [original, backup] = l.split('\t');
+          return { original, backup };
+        })
+    : [];
+  for (const e of edits) fs.copyFileSync(path.join(runDir, e.backup), e.original);
+  for (const m of moves.toReversed()) {
+    const from = path.join(root, m.destino);
+    const to = path.join(root, m.origem);
+    if (fs.existsSync(from) && !fs.existsSync(to)) fs.renameSync(from, to);
+  }
+  return { moves: moves.length, edits: edits.length };
+}
+
+function validateMoves(root, moves) {
+  const problems = [];
+  for (const m of moves) {
+    const from = path.join(root, m.origem);
+    const to = path.join(root, m.destino);
+    if (!isInside(from, root) || !isInside(to, root)) problems.push(`${m.origem}: fora do projeto`);
+    else if (['_wizz', '.git'].includes(m.origem.split('/')[0])) problems.push(`${m.origem}: pasta protegida`);
+    else if (!fs.existsSync(from)) problems.push(`${m.origem}: não existe`);
+    else if (fs.existsSync(to)) problems.push(`${m.destino}: destino já existe`);
+  }
+  return problems;
+}
+
+function applyMoves(root, moves, opts) {
+  const config = lib.readConfig(root);
+  const problems = validateMoves(root, moves);
+  if (problems.length > 0) return { ok: false, code: 2, line: `Nada foi movido: ${problems.join('; ')}.` };
+
+  const runDir = path.join(archiveDir(root, config.layout), stamp());
+  fs.mkdirSync(runDir, { recursive: true });
+  writeManifest(path.join(runDir, 'manifesto.tsv'), moves);
+
+  const before = runTests(root, opts.testes);
+
+  // Referências: projeto inteiro + pastas extras (auto-memória, Cérebro).
+  const extra = typeof opts.refs === 'string' ? opts.refs.split(',').map((d) => path.resolve(root, d.trim())) : [];
+  const skip = [archiveDir(root, config.layout)];
+  const targets = new Set();
+  for (const base of [root, ...extra]) for (const f of walkText(base, skip)) targets.add(f);
+  const movedAbs = new Set(moves.map((m) => path.join(root, m.origem)));
+
+  // 1) Backup + reescrita ANTES de mover: o backup guarda o texto original.
+  const edits = [];
+  let n = 0;
+  for (const file of targets) {
+    const text = fs.readFileSync(file, 'utf8');
+    const dir = movedAbs.has(file) ? '' : path.dirname(file) === root ? '' : path.dirname(file);
+    const next = rewriteRefs(text, moves, dir);
+    if (next === text) continue;
+    const backup = path.join('antes', String(++n).padStart(4, '0') + '-' + path.basename(file));
+    fs.mkdirSync(path.join(runDir, 'antes'), { recursive: true });
+    fs.copyFileSync(file, path.join(runDir, backup));
+    // Arquivo que também muda de lugar: o desfazer restaura no caminho NOVO e
+    // só depois devolve o move; restaurar no antigo deixaria uma cópia órfã.
+    const moved = moves.find((m) => path.join(root, m.origem) === file);
+    edits.push({ original: moved ? path.join(root, moved.destino) : file, backup });
+    fs.writeFileSync(file, next);
+  }
+  fs.writeFileSync(
+    path.join(runDir, 'edicoes.tsv'),
+    edits.map((e) => `${e.original}\t${e.backup}`).join('\n') + (edits.length > 0 ? '\n' : ''),
+  );
+
+  // 2) Moves.
+  for (const m of moves) {
+    const to = path.join(root, m.destino);
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    fs.renameSync(path.join(root, m.origem), to);
+  }
+  const undoFile = writeUndoScript(runDir, root, moves, edits);
+  const after = runTests(root, opts.testes);
+  const relRun = path.relative(root, runDir);
+
+  if (before && after && before.ok && !after.ok && !opts.manter) {
+    undo(root, runDir);
+    return {
+      ok: false,
+      code: 1,
+      line: `Os testes passavam antes e quebraram depois: desfiz tudo. Últimas linhas: ${after.tail}. Registro em ${relRun}/.`,
+    };
+  }
+  const testes = before
+    ? ` Testes: antes ${before.ok ? 'ok' : `falhando (${before.code})`}, depois ${after.ok ? 'ok' : `falhando (${after.code})`}.`
+    : ' Sem comando de testes (--testes): confira à mão.';
+  return {
+    ok: !after || after.ok || !before?.ok,
+    code: 0,
+    line: `Movi ${moves.length} arquivo(s) e atualizei referências em ${edits.length}.${testes} Desfazer: ${path.relative(root, undoFile)}.`,
+  };
+}
+
+function cmdAplicar(root, opts) {
+  const file = opts._[1];
+  if (!file) return { ok: false, code: 2, line: 'Uso: aplicar <manifesto.tsv>.' };
+  const moves = readManifest(path.resolve(root, file));
+  if (moves.length === 0) return { ok: false, code: 2, line: 'Manifesto vazio: nada a fazer.' };
+  return applyMoves(root, moves, opts);
+}
+
+function cmdMover(root, opts) {
+  const [, origem, destino] = opts._;
+  if (!origem || !destino) return { ok: false, code: 2, line: 'Uso: mover <origem> <destino>.' };
+  const relOf = (p) => path.relative(root, path.resolve(root, p));
+  return applyMoves(root, [{ origem: relOf(origem), destino: relOf(destino) }], opts);
+}
+
+function cmdDesfazer(root, opts) {
+  const dir = opts._[1];
+  if (!dir) return { ok: false, code: 2, line: 'Uso: desfazer <pasta-da-arrumacao>.' };
+  const runDir = path.resolve(root, dir);
+  if (!fs.existsSync(path.join(runDir, 'manifesto.tsv'))) return { ok: false, code: 2, line: `Sem manifesto.tsv em ${dir}.` };
+  const r = undo(root, runDir);
+  return { ok: true, line: `Desfeito: ${r.moves} move(s) revertido(s), ${r.edits} arquivo(s) restaurado(s).` };
+}
+
+const COMMANDS = { layout: cmdLayout, planejar: cmdPlanejar, aplicar: cmdAplicar, mover: cmdMover, desfazer: cmdDesfazer };
+
+function run(argv) {
+  const opts = parseArgs(argv);
+  const command = COMMANDS[opts._[0]];
+  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 root = lib.findWizzRoot(cwd);
+  if (!root) return { ok: true, code: 0, line: 'Não é projeto Wizz (sem _wizz/): nada a fazer.' };
+  try {
+    return command(root, opts);
+  } catch (error) {
+    return { ok: false, code: 1, line: `Falhou: ${error.message}` };
+  }
+}
+
+if (require.main === module) {
+  const result = run(process.argv.slice(2));
+  process.stdout.write(`${result.line}\n`);
+  process.exit(result.code ?? (result.ok ? 0 : 1));
+}
+
+module.exports = { run, rewriteRefs, readManifest, planMoves, undo };