wizz-method 2.15.0 → 2.17.0

package/tools/hooks/README.md

@@ -7,14 +7,26 @@ ela é substituída no próximo sync.
 | Hook                            | Evento             | O que faz                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | ------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `wizz-router-enforce.js`        | UserPromptSubmit   | Gate `isTrivial()` + injeção curta: em projeto Wizz (`_wizz/`) manda delegar direto ao maestro/agente da área (sem router); fora, manda pro `wizz-router`.                                                                                                                                                                                                                                                                          |
-| `session-rules.js`              | SessionStart       | Duas coisas num processo só: injeta as regras de comunicação 1x por sessão (antes era por prompt) e resolve a FEATURE ATIVA sozinho (branch git > `_wizz/bmm/config.yaml` > nada), para ninguém precisar invocar `wizz-set-feature`. Branch de tronco e de release não viram feature; sem feature a linha não é emitida (custo zero). A feature também é o `tema` da memória.                                                       |
+| `session-rules.js`              | SessionStart       | Duas coisas num processo só: injeta as regras de comunicação 1x por sessão (antes era por prompt) e resolve a FEATURE ATIVA sozinho (branch git > `_wizz/bmm/config.yaml` > nada), para ninguém precisar invocar `wizz-set-feature`. Branch de tronco e de release não viram feature. Fora de projeto Wizz e sem branch de feature a linha não é emitida (custo zero); dentro de projeto Wizz sem feature sai o lembrete curto "o primeiro pedido nomeado define uma", e sem `layout:` o lembrete de propor um. A feature também é o `tema` da memória.                                                       |
 | `security-defensive-context.js` | PreToolUse (Skill) | Metodologia defensiva/escopada ao invocar skills de segurança. Genérico por projeto (v2).                                                                                                                                                                                                                                                                                                                                           |
+| `wizz-artifact-guard.js`        | PostToolUse (Write) | Avisa (nunca bloqueia) artefato escrito fora da subpasta da feature ativa, artefato de feature sem feature ativa, frontmatter faltando em `<tipo>-<slug>.md`, e arquivo solto na raiz fora do `layout:`, com o comando que move. Fail-open sem `_wizz/` ou config. |
 | `rtk-rewrite.sh`                | PreToolUse (Bash)  | Reescreve comandos de shell via `rtk rewrite` (token economy). Fork local do hook gerado pelo instalador upstream do rtk, com 3 patches (auditoria 2026-07-07, C4/RT1; e 2026-09-11, RT-H3): reescrita linha a linha em comando multi-linha (o binário só reescrevia a 1ª linha), timeout interno por linha (`RTK_HOOK_TIMEOUT`, default 3s) que não depende do `timeout`/`gtimeout` do GNU coreutils, e cache do version-guard (`RTK_CACHE_TTL_SECONDS`, default 1h, em `${XDG_CACHE_HOME:-$HOME/.cache}/wizz/rtk-version`) pra não rodar `rtk --version` a cada `Bash` tool call da sessão. Requer `rtk` + `jq` no PATH; fail-open em ambos (e no cache: ilegível/corrompido/expirado recomputa em silêncio). |
 
+Arquivos de apoio (copiados junto, NUNCA registrados em settings.json; o doctor cobra a presença):
+
+| Arquivo | O que é |
+| --- | --- |
+| `wizz-feature-lib.js` | Funções puras de feature, git, config, pastas de artefato e frontmatter. Usada por todos os hooks acima. |
+| `wizz-layout-lib.js` | O que pode ficar na raiz e para onde vai o resto (tipos `codigo`, `scripts`, `dados`, `docs`, `midia`, `arquivo`). |
+| `wizz-feature.js` | CLI do ciclo de vida da feature: `resolver`, `definir`, `artefato`, `decidir`, `status`, `verificar`, `encerrar`, `listar`. É o passo verificável que router/maestro rodam antes de despachar. |
+| `wizz-arrumar.js` | CLI de arrumação: `layout [--gravar]`, `planejar`, `aplicar` (manifesto .tsv + referências + testes antes/depois + `desfazer.sh`), `mover`, `desfazer`. |
+
+Regra completa em `src/modules/wizz/_shared/organizacao.md` (2026-10-02, caso Spider). `session-rules.js` passou a lembrar "nenhuma feature ativa" e "projeto sem layout" dentro de projeto Wizz, e `wizz-router-enforce.js` acrescenta 1 linha de feature por prompt em projeto Wizz.
+
 Removidos em 2026-07 (arquivados em `~/.claude/hooks-archive/`):
 `no-narration-enforce.js` (absorvido pelo session-rules) e `vault-reminder.js`.
 
-Testes: `npm run test:hooks` (isTrivial + contexto por modo), `npm run test:feature-context` (resolução da feature ativa: tronco não vira feature, branch ganha do config, silêncio quando não há feature) e `node test/test-rtk-hook.js` (rewrite básico + multi-linha do `rtk-rewrite.sh`, smoke test que exercita o binário `rtk` real quando disponível, e o cache do version-guard: criado na 1ª chamada e reusado na 2ª, TTL expirado força recompute, path do binário mudou invalida, cache corrompido não quebra e se auto-cura).
+Testes: `npm run test:organizacao` (CLIs de feature e arrumação, guard, lembretes nos cenários sem git / main / branch), `npm run eval:feature` (hooks reais + CLI + estado final; `--llm` mede a obediência do modelo), `npm run test:hooks` (isTrivial + contexto por modo), `npm run test:feature-context` (resolução da feature ativa: tronco não vira feature, branch ganha do config, silêncio quando não há feature) e `node test/test-rtk-hook.js` (rewrite básico + multi-linha do `rtk-rewrite.sh`, smoke test que exercita o binário `rtk` real quando disponível, e o cache do version-guard: criado na 1ª chamada e reusado na 2ª, TTL expirado força recompute, path do binário mudou invalida, cache corrompido não quebra e se auto-cura).
 Evals de roteamento: `node evals/routing/run-routing-eval.mjs [--llm]`.
 
 Drift repo ↔ global: `npm run sync:check` compara hash de cada hook (e skill) entre o repo e `~/.claude`, sem escrever nada — é lembrete (fail-open), não gate; roda no fim do `npm test`. Achou drift? `npm run sync:global` atualiza `~/.claude`.

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(' ');
 }