wizz-method 2.13.0 → 2.14.0

package/tools/installer/core/installer.js

@@ -20,6 +20,7 @@ const { buildHookEntries, filterHooksRegisteredGlobally, mergeHooksIntoSettings
 
 const { ExistingInstall } = require('./existing-install');
 const { warnPreNativeSkillsLegacy } = require('./legacy-warnings');
+const { applyProjectInstructions, removeProjectInstructions } = require('./project-instructions');
 const userFilePreservation = require('./user-file-preservation');
 const moduleConfigWriter = require('./module-config-writer');
 const helpCatalog = require('./help-catalog');
@@ -808,6 +809,11 @@ class Installer {
           addResult('Hooks settings', 'ok', `${pendingHooksSettingsWrite.count} hook(s) → .claude/settings.json${skippedDetail}`);
         }
 
+        // Bloco gerenciado no CLAUDE.md/AGENTS.md (2026-09-30): sem ele, um
+        // CLAUDE.md antigo vence as regras do Wizz, que chegam só por hook.
+        // Depois do swap pelo mesmo motivo do settings.json: vive fora de _wizz/.
+        await this._applyProjectInstructions(paths, config, addResult);
+
         await this._appendPreservedSkillManifestRows(paths.wizzDir, previousSkillManifestRows, preservedModules);
 
         // Apply post-install --set TOML patches. Runs after writeCentralConfig
@@ -1223,6 +1229,31 @@ class Installer {
    * @param {string} file
    * @returns {Promise<{settings: object, invalidJson: boolean}>}
    */
+  async _applyProjectInstructions(paths, config, addResult) {
+    if (!(await fs.pathExists(path.join(paths.wizzDir, 'wizz')))) return;
+    try {
+      const results = await applyProjectInstructions({
+        projectRoot: paths.projectRoot,
+        fs,
+        createIfMissing: (config.ides || []).includes('claude-code'),
+      });
+      for (const r of results) {
+        const name = path.basename(r.file);
+        const legacy = r.findings.length > 0 ? `, ${r.findings.length} trecho(s) legado(s) marcados` : '';
+        addResult('Project instructions', r.findings.length > 0 ? 'warn' : 'ok', `bloco Wizz no topo de ${name}${legacy}`);
+      }
+      const totalLegacy = results.reduce((n, r) => n + r.findings.length, 0);
+      if (totalLegacy > 0) {
+        await prompts.log.warn(
+          `${totalLegacy} regra(s) antiga(s) no CLAUDE.md/AGENTS.md (GSD, superpowers, BMAD puro ou modelo aposentado). O bloco Wizz no topo tem prioridade, mas vale limpar: rode wizz doctor para ver as linhas.`,
+        );
+      }
+    } catch (error) {
+      await prompts.log.warn(`Falha ao gravar o bloco Wizz no CLAUDE.md/AGENTS.md: ${error.message}`);
+      addResult('Project instructions', 'warn', error.message);
+    }
+  }
+
   async _readSettingsJson(file) {
     if (!(await fs.pathExists(file))) return { settings: {}, invalidJson: false };
     try {
@@ -1600,6 +1631,7 @@ class Installer {
     // 2. IDE CLEANUP (before _wizz/ deletion so configs are accessible)
     if (options.removeIdeConfigs !== false) {
       await this.uninstallIdeConfigs(projectDir, existingInstall, { silent: options.silent });
+      await removeProjectInstructions({ projectRoot: projectDir, fs });
       removed.ideConfigs = true;
     }
 

package/tools/installer/core/project-instructions.js

@@ -0,0 +1,199 @@
+// project-instructions.js — bloco gerenciado no CLAUDE.md/AGENTS.md do projeto.
+//
+// Motivo (2026-09-30): o Claude Code carrega o CLAUDE.md do projeto como
+// instrução de projeto (prioridade alta), enquanto as regras do Wizz chegam
+// por hook e skill (contexto extra, prioridade menor). Num projeto que já
+// tinha CLAUDE.md antigo (GSD, superpowers, BMAD puro, modelos aposentados),
+// a regra velha vencia a nova. O installer agora grava um bloco no TOPO do
+// arquivo dizendo que o Wizz vence em conflito e listando os trechos legados
+// detectados. Nada fora do bloco é apagado ou reescrito.
+//
+// Lógica pura (texto → texto) + um aplicador fino com fs injetável, para os
+// testes não dependerem de disco real.
+
+const path = require('node:path');
+const fsp = require('node:fs/promises');
+
+const BLOCK_BEGIN = '<!-- wizz:begin -->';
+const BLOCK_END = '<!-- wizz:end -->';
+const INSTRUCTION_FILES = ['CLAUDE.md', 'AGENTS.md'];
+
+// IDs de modelo aposentados. Compartilhado com tools/validate-model-ids.mjs.
+// claude-haiku-4-5 continua atual (não há Haiku mais novo em 2026-09-30).
+// `claude-(opus|sonnet)-5` sem sufixo foi trocado por 5-5; o lookahead evita
+// casar o próprio `-5-5`.
+const RETIRED_MODEL_RE =
+  /\bclaude-(?:instant|2|3|3-5|3-7)(?:-[a-z0-9]+)*\b|\bclaude-(?:opus|sonnet)-4(?:-\d+)?\b|\bclaude-(?:opus|sonnet)-5\b(?!-)/gi;
+
+const LEGACY_RULES = [
+  { id: 'gsd', re: /\bGSD\b|get-shit-done|\/gsd[:-]/, why: 'GSD foi substituído pelas fases e checkpoints do Wizz Method' },
+  { id: 'superpowers', re: /\bsuperpowers\b/i, why: 'superpowers foi substituído pelo Wizz Method' },
+  {
+    id: 'bmad',
+    re: /_bmad\/|\/bmad[-:]|\bbmad-(?:master|agent|method|help)\b/i,
+    why: 'comandos e pastas do BMAD puro viraram wizz-* e _wizz/',
+  },
+  { id: 'modelo-aposentado', re: RETIRED_MODEL_RE, why: 'ID de modelo aposentado; a escada do Wizz usa os apelidos atuais' },
+];
+
+const MAX_SNIPPET = 120;
+
+// project-context.md (2026-09-30, porte do BMAD 6.12 #2750): em vez de cada
+// skill procurar o arquivo em toda ativação (persistent_facts), o bloco
+// importa uma vez por sessão. Busca rasa, pulando pastas de dependência/build.
+const CONTEXT_FILE = 'project-context.md';
+const CONTEXT_MAX_DEPTH = 4;
+const CONTEXT_SKIP_DIRS = new Set(['node_modules', '.git', '_wizz', '.claude', 'build', 'dist', '.next', 'vendor', '.venv']);
+
+/** Caminho relativo (posix) do project-context.md mais raso, ou null. */
+async function findProjectContext(projectRoot) {
+  let level = [projectRoot];
+  for (let depth = 0; depth <= CONTEXT_MAX_DEPTH && level.length > 0; depth++) {
+    const next = [];
+    for (const dir of level.sort()) {
+      let entries;
+      try {
+        entries = await fsp.readdir(dir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      if (entries.some((e) => e.isFile() && e.name === CONTEXT_FILE)) {
+        return path.relative(projectRoot, path.join(dir, CONTEXT_FILE)).split(path.sep).join('/');
+      }
+      for (const e of entries) if (e.isDirectory() && !CONTEXT_SKIP_DIRS.has(e.name)) next.push(path.join(dir, e.name));
+    }
+    level = next;
+  }
+  return null;
+}
+
+/** Linha de contexto por arquivo: CLAUDE.md importa com @; AGENTS.md só aponta. */
+function contextLine(fileName, contextPath) {
+  if (!contextPath) return null;
+  return fileName === 'CLAUDE.md'
+    ? `Contexto do projeto (regras de stack e padrões, importado uma vez por sessão):\n@${contextPath}`
+    : `- Contexto do projeto: leia \`${contextPath}\` antes de implementar (regras de stack e padrões).`;
+}
+
+/** Separa o bloco gerenciado do resto do arquivo. */
+function splitManagedBlock(text) {
+  const start = text.indexOf(BLOCK_BEGIN);
+  const end = text.indexOf(BLOCK_END);
+  if (start === -1 || end === -1 || end < start) return { block: null, rest: text };
+  const after = text.slice(end + BLOCK_END.length).replace(/^\r?\n+/, '');
+  return { block: text.slice(start, end + BLOCK_END.length), rest: text.slice(0, start) + after };
+}
+
+/**
+ * Procura regras legadas no texto, pulando as linhas do bloco gerenciado.
+ * `line` é a linha real no arquivo (1-based), para o doctor apontar.
+ * @returns {{id: string, line: number, snippet: string, why: string}[]}
+ */
+function scanLegacy(text) {
+  const findings = [];
+  let inBlock = false;
+  for (const [i, line] of text.split(/\r?\n/).entries()) {
+    if (line.includes(BLOCK_BEGIN)) inBlock = true;
+    if (inBlock) {
+      if (line.includes(BLOCK_END)) inBlock = false;
+      continue;
+    }
+    const rule = LEGACY_RULES.find((r) => new RegExp(r.re.source, r.re.flags.replace('g', '')).test(line));
+    if (rule) findings.push({ id: rule.id, line: i + 1, snippet: line.trim().slice(0, MAX_SNIPPET), why: rule.why });
+  }
+  return findings;
+}
+
+/** Monta o bloco. Sem número de linha: o próprio bloco desloca as linhas. */
+function renderManagedBlock(findings = [], context = null) {
+  const lines = [
+    BLOCK_BEGIN,
+    '<!-- Gerenciado pelo Wizz Method: o install reescreve este bloco. Edite fora dele. -->',
+    '## Wizz Method: estas regras têm prioridade',
+    '',
+    'Este projeto usa o Wizz Method (`_wizz/`). Se alguma instrução deste arquivo, fora deste bloco, contradizer o Wizz Method, vale o Wizz Method.',
+    '',
+    '- Pedido não trivial: uma área vai para o agente da área; duas ou mais áreas vão para o `wizz-maestro`. Edição trivial de 1 linha e conversa executam direto.',
+    '- Planejamento, TDD, checkpoints e review seguem o Wizz Method. Não usar GSD, superpowers nem os comandos antigos do BMAD (`/bmad-*`, `_bmad/`).',
+    '- Modelos seguem a escada do Wizz (`wizz-exec-mechanical`, `-standard`, `-strong`, `-ultra`, `-review`), que usa os apelidos atuais. Ignore IDs de modelo fixos deste arquivo.',
+  ];
+  if (context) lines.push('', ...context.split('\n'));
+  if (findings.length > 0) {
+    lines.push('', 'Trechos legados detectados abaixo (não valem mais; `wizz doctor` lista de novo):');
+    for (const f of findings) lines.push(`- \`${f.snippet.replaceAll('`', "'")}\` (${f.why})`);
+  }
+  lines.push(BLOCK_END);
+  return lines.join('\n');
+}
+
+/** Insere ou substitui o bloco no topo. Idempotente. */
+function upsertManagedBlock(text, context = null) {
+  const { rest } = splitManagedBlock(text);
+  const findings = scanLegacy(rest);
+  const block = renderManagedBlock(findings, context);
+  const body = rest.replace(/^\s+/, '');
+  return { text: body ? `${block}\n\n${body}` : `${block}\n`, findings };
+}
+
+/** Remove o bloco (uninstall). Devolve o texto intacto se não houver bloco. */
+function removeManagedBlock(text) {
+  return splitManagedBlock(text).rest;
+}
+
+/**
+ * Aplica o bloco nos arquivos de instrução que existem na raiz do projeto.
+ * Sem nenhum dos dois, cria CLAUDE.md só se `createIfMissing`.
+ * Com project-context.md no projeto, o bloco importa (CLAUDE.md) ou aponta (AGENTS.md) para ele.
+ * @returns {Promise<{file: string, changed: boolean, findings: object[]}[]>}
+ */
+async function applyProjectInstructions({ projectRoot, fs, createIfMissing = false }) {
+  const results = [];
+  const targets = [];
+  for (const name of INSTRUCTION_FILES) {
+    const file = path.join(projectRoot, name);
+    if (await fs.pathExists(file)) targets.push(file);
+  }
+  if (targets.length === 0 && createIfMissing) targets.push(path.join(projectRoot, 'CLAUDE.md'));
+
+  const contextPath = await findProjectContext(projectRoot);
+  for (const file of targets) {
+    const before = (await fs.pathExists(file)) ? await fs.readFile(file, 'utf8') : '';
+    const { text, findings } = upsertManagedBlock(before, contextLine(path.basename(file), contextPath));
+    const changed = text !== before;
+    if (changed) await fs.writeFile(file, text, 'utf8');
+    results.push({ file, changed, findings });
+  }
+  return results;
+}
+
+/** Tira o bloco dos arquivos de instrução (uninstall). */
+async function removeProjectInstructions({ projectRoot, fs }) {
+  const removed = [];
+  for (const name of INSTRUCTION_FILES) {
+    const file = path.join(projectRoot, name);
+    if (!(await fs.pathExists(file))) continue;
+    const before = await fs.readFile(file, 'utf8');
+    const after = removeManagedBlock(before);
+    if (after !== before) {
+      await fs.writeFile(file, after, 'utf8');
+      removed.push(file);
+    }
+  }
+  return removed;
+}
+
+module.exports = {
+  BLOCK_BEGIN,
+  BLOCK_END,
+  INSTRUCTION_FILES,
+  findProjectContext,
+  contextLine,
+  RETIRED_MODEL_RE,
+  splitManagedBlock,
+  scanLegacy,
+  renderManagedBlock,
+  upsertManagedBlock,
+  removeManagedBlock,
+  applyProjectInstructions,
+  removeProjectInstructions,
+};