wizz-method 2.20.1 → 2.22.0

package/src/skills-lib/wizz-vsl/references/offer.md

@@ -0,0 +1,91 @@
+# Phase 4.1 · The OFFER (written first)
+
+> Counterintuitive and non-negotiable: **the offer is the first block written**, even though it is the last the viewer sees. Prerequisite: `manifest.gate2_aprovado_em` filled in. Check it before writing.
+>
+> When an approved `wizz-offer-forge` offer exists, it is the source for steps 2 to 13 (name, stack, bonuses, guarantee, anchor): this block turns it into **spoken** script, it does not redesign it. A change of price, bonus or guarantee goes back to `wizz-offer-forge` and reopens Gate 2.
+
+Default position: the pitch enters at the 12 to 14 minute turn and runs 4 to 6 more (full VSL 16 to 20). Under the low ticket ruler, the pitch enters at about two thirds of the runtime the ruler sets.
+
+## The 15 steps, in order
+
+**1. Transition from the mechanism to the offer.**
+> "Agora que você entendeu <mecanismo da solução>, deixa eu te mostrar como aplicar isso na sua vida a partir de hoje."
+
+Never cut dry to "so I created a course".
+
+**2. Product name.** Strong and specific. Words that convey a system (*protocolo, método, sistema, programa, desafio*). Avoid *curso* and *formação*: they sound like content, not result.
+
+**3. Who it is for, and who it is not for.**
+> "Isso é pra você se <condição 1>, <condição 2> e <condição 3>. E não é pra você se <condição>."
+
+The negative qualification raises perceived value and buyer quality (Block 1.9).
+
+**4. What the person receives.** Module by module, always **benefit, not feature**:
+> ❌ "Módulo 3: Alimentação"
+> ✅ "Módulo 3: o que comer nos dias em que a agenda vira do avesso, pra você não recomeçar do zero toda segunda"
+
+**5. The triad.** Strong products communicate three layers:
+
+| Layer | Line | Example |
+|---|---|---|
+| **Knowledge** | "Eu te ensino a pescar" | the content, straight to the point |
+| **Recommendation** | "Eu te dou o peixe" | what to do in her specific case (diagnosis, plan, AI) |
+| **Follow-up** | "Eu te acompanho na pescaria" | continuous support: group, WhatsApp, AI, team |
+
+Name the layers that exist and never invent the missing ones. If two are missing, flag it to the human: it is an offer weakness, not a copy one.
+
+**6. Interleaved testimonials.** `[DEPOIMENTO 1]`, `[DEPOIMENTO 2]`… spread **between** modules, never piled in one block. When there is no proof material, the markers hold the place, or the block is omitted; the rest of the pitch goes on.
+
+**7. Price anchoring.** Before revealing the price, compare with the real, expensive alternative:
+> "Uma consultoria individual comigo sai R$ X por sessão. Um acompanhamento de 3 meses passa de R$ Y."
+
+Anchor only against a real, supported alternative. A charging history or discount that never existed is never stated as fact.
+
+**8. Price with contrast** · `[BOTÃO APARECE AQUI]`
+> "Mas hoje não é nada disso. É R$ <preço>."
+
+The button appears **here**, when the price is revealed: that is what the player delay waits for.
+
+**9. Bonus with a 60-second timer.** A real urgency bonus with a visual countdown, typically a live workshop seat. It is one of the strongest levers of the format. Honesty requirement: the bonus exists and is delivered. A timer that resets and keeps offering destroys trust in the whole funnel.
+
+**10. Guarantee.** Period and condition, in one clear sentence that matches the real terms exactly (an encouraged usage challenge is not automatically a refund condition).
+
+**11. Extra bonuses, with a story.** Each bonus gets 2 or 3 lines of origin. A bonus listed without story is noise; with story it is value.
+
+**12. Express stack.** Quick recap, in a list, with value per item:
+> "Programa completo: R$ X · Bônus 1: R$ Y · Bônus 2: R$ Z · Total: R$ <soma>. Hoje: R$ <preço>."
+
+**13. Surprise gift.**
+> "E tem uma coisa que eu nem coloquei na lista: assim que você entrar, recebe um convite pra <aula/encontro>."
+
+It raises the open rate of the first post-purchase message, where the whole backend starts.
+
+**14. Emotional close.** Go back to the lead's problem and project the two futures.
+
+**15. Final CTA.** One instruction, no ambiguity: "Clica no botão aqui embaixo agora." `[CTA → aponta pro botão que já apareceu no passo 8]`
+
+## The value equation (apply to every line of the pitch)
+
+Every element of the offer pushes at least one of: **↑ dream outcome · ↑ perceived likelihood · ↓ time to result · ↓ effort and sacrifice**. A bonus or module that moves none of the four weakens the offer by dilution.
+
+## Page and player rules (they move conversion more than copy)
+
+These belong to the page around the player, written by `wizz-copywriting`; list them in the hand-off.
+
+| Rule | Why |
+|---|---|
+| **No headline above the video** | Removing the headline improves play rate |
+| **No email or phone form before the VSL** | Capturing first lowers front-end conversion |
+| **Delayed button**, only after the price | An early button anticipates the pitch and lowers retention |
+| **No discount button or coupon on the page** | Discount buyers take the upsell far less |
+| Traffic goes straight to the open page | No intermediate capture step |
+
+Under the low ticket ruler, its page and player shards (`06b-player-vsl.md`, `12c-anatomia-low-ticket.md`) win over this table.
+
+## Output of this step
+
+The offer block in **spoken language** (it is a script, not page text), with `[DEPOIMENTO]`, `[BOTÃO APARECE AQUI]` and `[A DEFINIR]` markers where information is missing.
+
+## OTO and downsell videos
+
+A short upsell video after purchase follows a different sequence, in [blocks-and-leads.md](blocks-and-leads.md) §OTO. It never implies that the buyer accepted another optional offer.

package/src/skills-lib/wizz-vsl/references/production.md

@@ -0,0 +1,75 @@
+# Phase 6 · Production plan and hand-off
+
+> Animation makes a clear script easier to follow; it cannot rescue vague writing. Production starts only after the script-only audit and the claims ledger are closed ([assembly-qa.md](assembly-qa.md)). This skill **plans** the production and hands it off: drawing, voicing and assembling the video belong to the designer area. The copy agent never invokes another area's agent: offer `wizz-maestro` when the user wants the video in the same delivery.
+
+## 1. Beat sheet · `05-beat-sheet.md`
+
+One row per beat, in presentation order. It is the contract the production reads.
+
+| # | Narration (exact) | On-screen line | Visual evidence | Claim supported | Source |
+|---|---|---|---|---|---|
+| 1 | "…" | ≤ 6 words | product crop / real screen / `[B-ROLL: …]` | ledger #3 | `00-briefing.md` 7.4 |
+
+- Capture product states only after confirming the script and the UI agree. Label fixture or example data honestly. Never expose customer data, credentials or live keys.
+- A small visual system: two type roles, a restrained palette, consistent safe margins, a few repeatable scene types (intro, problem, reveal, demo, proof, guarantee, offer, CTA). Patterns, not required branding: the project's brand wins.
+- No durations by hand: every beat's length comes from the final audio (section 3).
+
+## 2. Narration
+
+- Record or generate the narration from the **exact** final script. Paid voice generation only with the user's explicit authorization; keep the complete inputs (text, voice and model settings, request IDs, returned alignment, audio hashes) so an uncertain job is resumed instead of paid twice.
+- When revising, regenerate only the changed sentences if the voice splices cleanly, with adjacent text as prosody context. Listen to every seam; replace the whole paragraph only when the splice stays audible.
+
+## 3. Timing from the final audio
+
+Invoke the `wizz-ctc-align` skill on the final narration and the exact spoken text: word-by-word timestamps snapped to real silences become the single timing source. Never estimate timing by hand and never use Whisper timestamps for a known script.
+
+- Scene durations are built from that alignment.
+- Big on-screen lines change on **spoken beats**, anchored to the word timings, never to arbitrary seconds.
+- If a section is cut after alignment, update audio, word timings, captions, scene hosts, animation anchors, music ducking and the final fade **together**. Old offsets become invalid after an upstream edit.
+
+## 4. Drawing and assembly (designer area)
+
+The method's video pipeline rule: **HyperFrames draws the screens (silent visual), Remotion assembles the film (audio, captions, frame timing).**
+
+- `hyperframes` draws each silent scene from the beat sheet: kinetic headline cards, animated stack, price reveal, guarantee card, real product mockups.
+- The `wizz-remotion-best-practices` skill assembles the scenes with the narration, captions, SFX and the motion anchored to the `wizz-ctc-align` timings.
+- Effects and sound by semantic event, if wanted: the `wizz-video-effects` skill, after the assembly plan.
+
+### Motion rules for the big lines
+
+- Split on-screen headlines into one to three short lines, each a complete, concrete thought.
+- Enter lines in sequence with fast, damped motion; use scale, opacity or horizontal movement consistently.
+- Highlight one decisive line or word with the accent colour; never colour every benefit.
+- Keep copy readable after its entrance. Motion marks a beat, reveals evidence or guides focus.
+- During demos the UI dominates: crops and pans focus attention without hiding the state needed to verify the claim. When the finished output is the strongest proof, play it unobstructed and long enough to judge.
+- Respect title-safe areas, captions, mobile scaling and reduced motion.
+
+**Illustrated VSL (optional reference).** For a slide-by-slide stickman or illustrated VSL with a timed image manifest and frame verification, `mikefilsaime-groove/stickman-vsl-director` (MIT) is a reference for the storyboard grammar (one image per narration span, a mandatory art-direction choice, a review deck before rendering). It is not installed by the method; its own scripts are not run from here.
+
+## 5. Verification of the rendered master
+
+- Inspect frames from the rendered master, not only development snapshots.
+- Watch with sound from start to end; listen at every splice and transition.
+- Check captions against the final audio and the visible claims.
+- No black gaps, clipped lines, stale frames, drift, missing fonts or unreadable demo crops.
+- Measure streams, dimensions, runtime, loudness, peaks, file size and hashes when relevant. Keep a high-quality master separate from the web encode.
+
+## 6. Player QA (on the real page)
+
+Test the actual page player on phone width and desktop: explicit sound start, restart behaviour, native controls, captions, close or escape, pause when out of viewport, poster, reduced motion, and the button delay set to the price moment (`[BOTÃO APARECE AQUI]`). Under the low ticket ruler, `06b-player-vsl.md` of `wizz-lowticket-metodologia` sets what the player must deliver.
+
+Report the measured runtime and the remaining limitations. Nothing is published, deployed, or sent to paid generation without the user's authorization.
+
+## Hand-off block
+
+Close Phase 6 with this block in the reply:
+
+```
+🎬 HANDOFF DE PRODUÇÃO · <produto>
+Roteiro final: {output_folder}/vsl/<slug>/03-vsl-principal.md (lead default: <qual>)
+Beat sheet: {output_folder}/vsl/<slug>/05-beat-sheet.md (<N> beats)
+Ledger de claims: 04-qa.md (<N> claims, <N> com marcador pendente)
+Régua: <default | lowticket: duração e posição do pitch>
+Ordem: narração final → wizz-ctc-align → hyperframes (cenas mudas) → Remotion (montagem) → QA do player
+Página em volta do player: wizz-copywriting com as regras de página e player
+```

package/tools/hooks/README.md

@@ -12,18 +12,19 @@ ela é substituída no próximo sync.
 | `wizz-artifact-guard.js`        | PostToolUse (Write/Edit) | 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.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `wizz-close-reminder.js`        | Stop                     | Aviso ao usuário (`systemMessage`, nunca `decision: block`) quando a feature ativa está `implementado`/`no-ar` e o checklist de fechamento do `wizz-feature.js` tem pendência (ou está no ar e segue ativa). Sem subprocesso, sai cedo fora de projeto Wizz e com feature em andamento, não repete o mesmo aviso na sessão, fail-open.                                                                                                                                                                                                                                                                                                                                                                          |
 | `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). |
-| `rtk-rewrite.js`                | PreToolUse (Bash)        | Versão Node do `rtk-rewrite.sh`, registrada no lugar dele só no Windows (sem bash e jq garantidos lá), desde 2026-10-15. Mesmo contrato: guard de multi-linha, linha a linha, timeout por linha, piso 0.23.0, fail-open. Sem o cache de versão. `node test/test-rtk-hook-node.js` exige a mesma saída dos dois contra o mesmo `rtk` fake. |
+| `rtk-rewrite.js`                | PreToolUse (Bash)        | Versão Node do `rtk-rewrite.sh`, registrada no lugar dele só no Windows (sem bash e jq garantidos lá), desde 2026-10-15. Mesmo contrato: guard de multi-linha, linha a linha, timeout por linha, piso 0.23.0, fail-open. Sem o cache de versão. `node test/test-rtk-hook-node.js` exige a mesma saída dos dois contra o mesmo `rtk` fake.                                                                                                                                                                                                                                                                                                                                                                       |
 
 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-cerebro-lib.js` | Grava o fechamento no Cérebro (`encerrar --cerebro`): acha o vault e `projetos/<projeto>.md`, atualiza a linha da feature e a `Última sessão` do bloco Estado e põe 1 linha em Sessões (teto 15; as antigas vão para `_index/cerebro-archive.md`, lido só por grep). Idempotente, fail-open.                                  |
-| `wizz-debug-lib.js`   | Diagnóstico opt-in dos hooks: com `WIZZ_DEBUG=1` cada erro engolido vira 1 linha em stderr e é anexada a `~/.claude/wizz-debug.log` (`WIZZ_DEBUG_FILE` troca o caminho). Sem a variável: zero saída, zero disco. Os hooks seguem fail-open (exit 0). O `wizz doctor` roda cada hook com esse modo ligado (check `hooks-run`). |
-| `wizz-feature.js`     | CLI do ciclo de vida da feature: `resolver`, `definir`, `artefato`, `decidir`, `status`, `verificar`, `encerrar [--cerebro]`, `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`.                                                                                                                                                                       |
+| 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-cerebro-lib.js`        | Grava o fechamento no Cérebro (`encerrar --cerebro`): acha o vault e `projetos/<projeto>.md`, atualiza a linha da feature e a `Última sessão` do bloco Estado e põe 1 linha em Sessões (teto 15; as antigas vão para `_index/cerebro-archive.md`, lido só por grep). Idempotente, fail-open.                                  |
+| `wizz-debug-lib.js`          | Diagnóstico opt-in dos hooks: com `WIZZ_DEBUG=1` cada erro engolido vira 1 linha em stderr e é anexada a `~/.claude/wizz-debug.log` (`WIZZ_DEBUG_FILE` troca o caminho). Sem a variável: zero saída, zero disco. Os hooks seguem fail-open (exit 0). O `wizz doctor` roda cada hook com esse modo ligado (check `hooks-run`). |
+| `wizz-sprint-archive-lib.js` | Arquivamento do `encerrar`: planeja antes de tocar no disco (mescla com `_arquivo/<slug>/`, o de mesmo nome vai para o lado como `.anterior-<data>`, dono do `sprint-status.yaml` da raiz, links e referências de fora) e aplica com desfazer.                                                                                |
+| `wizz-feature.js`            | CLI do ciclo de vida da feature: `resolver`, `definir`, `artefato`, `decidir`, `status`, `verificar`, `encerrar [--cerebro]`, `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.
 

package/tools/hooks/wizz-arrumar.js

@@ -524,6 +524,7 @@ module.exports = {
   isAllowedTestArgv,
   resolveTestCommand,
   rewriteRefs,
+  walkText,
   readManifest,
   planMoves,
   undo,

package/tools/hooks/wizz-artifact-guard.js

@@ -9,6 +9,8 @@
 //   1. Artefato fora do lugar: escrito na pasta de artefatos mas fora da
 //      subpasta da feature ativa, artefato de feature sem feature ativa, ou
 //      artefato tipado (`spec-x.md`...) com frontmatter faltando/errado.
+//      Gravar num sprint arquivado (`_arquivo/<slug>/`) também avisa, e o
+//      arquivo solto direto em `_arquivo/` não tem dono (2026-10-24).
 //   2. Arquivo solto na raiz: fora do `layout:` do config. Sugere o destino e
 //      o comando que move atualizando as referências.
 //
@@ -73,13 +75,37 @@ function artifactWarning(file, content, state, { frontmatterOnly = false } = {})
   const slug = state.slug;
   const msgs = [];
 
+  const archived = parts[0] === lib.ARCHIVE_DIR;
+  // Arquivo direto em `_arquivo/` não é de sprint nenhum: o dono não é o nome dele.
+  const looseInArchive = archived && parts.length === 2;
+  const owner = archived ? (looseInArchive ? '' : parts[1]) : parts[0];
+  // O caminho dentro do sprint (com as subpastas), para o "mova para".
+  const within = parts.length === 1 ? parts : parts.slice(archived ? 2 : 1);
+  const inSprint = (sprint) => path.relative(state.root, path.join(base, sprint, ...within));
+
+  // Sprint fechado é histórico: avisa em Write e Edit, o sprint não reabre sozinho.
+  if (archived && !looseInArchive) {
+    msgs.push(
+      `SPRINT ARQUIVADO: ${relFile} está no sprint fechado "${owner}". ` +
+        (slug
+          ? `Trabalho novo entra no sprint aberto (${inSprint(slug)}); `
+          : 'Trabalho novo entra num sprint aberto (wizz-feature.js definir <slug>); ') +
+        'mexa no arquivo morto só para corrigir o histórico, a pedido do dono.',
+    );
+  } else if (looseInArchive && !frontmatterOnly) {
+    msgs.push(
+      `ARQUIVO SOLTO NO ARQUIVO MORTO: ${relFile} está direto em ${lib.ARCHIVE_DIR}/, fora de qualquer sprint fechado. ` +
+        `Mova para ${lib.ARCHIVE_DIR}/<slug>/ do sprint a que ele pertence.`,
+    );
+  }
+
   // Edit: o lugar já foi avisado quando o arquivo nasceu; só o frontmatter conta.
   if (!frontmatterOnly && parts.length === 1) {
     if (lib.PROJECT_WIDE.test(name)) return '';
     if (slug) {
       msgs.push(
         `ARTEFATO FORA DA FEATURE: ${relFile} está na raiz das pastas de artefato, mas a feature ativa é "${slug}". ` +
-          `Mova para ${path.relative(state.root, path.join(base, slug, name))} agora (raiz é só para artefato de projeto inteiro: arquitetura, contexto).`,
+          `Mova para ${inSprint(slug)} agora (raiz é só para artefato de projeto inteiro: arquitetura, contexto).`,
       );
     } else if (type) {
       msgs.push(
@@ -87,16 +113,16 @@ function artifactWarning(file, content, state, { frontmatterOnly = false } = {})
           `Grave a feature a partir do pedido (node ${HOOK_CMD}/wizz-feature.js definir <slug>) e mova o arquivo para a subpasta dela.`,
       );
     }
-  } else if (!frontmatterOnly && slug && parts[0] !== slug && parts[0] !== lib.ARCHIVE_DIR) {
+  } else if (!frontmatterOnly && slug && !archived && parts[0] !== slug) {
     msgs.push(
       `ARTEFATO EM OUTRO SPRINT: ${relFile} está em "${parts[0]}", mas o sprint aberto é "${slug}". ` +
-        `Trabalho novo entra no sprint aberto: mova para ${path.relative(state.root, path.join(base, slug, name))}. Abrir outro sprint só com a escolha do dono (wizz-feature.js definir <slug> --novo).`,
+        `Trabalho novo entra no sprint aberto: mova para ${inSprint(slug)}. Abrir outro sprint só com a escolha do dono (wizz-feature.js definir <slug> --novo).`,
     );
   }
 
   if (type) {
-    const owner = parts[0] === lib.ARCHIVE_DIR ? parts[1] : parts[0];
-    const problems = lib.frontmatterProblems(content, parts.length > 1 ? owner : slug);
+    const expected = parts.length > 1 ? owner : slug;
+    const problems = lib.frontmatterProblems(content, expected);
     if (problems.length > 0) msgs.push(`FRONTMATTER de ${relFile}: ${problems.join('; ')}.`);
   }
   return msgs.join(' ');

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

@@ -6,9 +6,10 @@
 // Estado + 1 linha na tabela Sessões" (`_shared/cerebro.md`).
 //
 // Regras do protocolo do Cérebro (skill `wizz-cerebro`, comandos-sessao.md):
-//   - vault: `~/Documents/projects/Obsidian Vault/CEREBRO.md`. O `find ~`
-//     do protocolo fica de fora (caro demais para uma CLI); quem usa outro
-//     lugar aponta `WIZZ_CEREBRO_VAULT` ou `cerebro_vault:` no config.
+//   - vault: mesma ordem da seção `## Vault` da skill (fonte única):
+//     `WIZZ_CEREBRO_VAULT` > `cerebro_vault:` no config > Cérebro por projeto
+//     (`<output_folder>/cerebro/`) > `~/Documents/projects/Obsidian Vault/`.
+//     O `find ~` do protocolo fica de fora (caro demais para uma CLI).
 //   - estado mora em `projetos/<nome>.md`, bloco `## Estado` no topo.
 //   - `Sessões` com teto de 15 linhas; nunca apagar histórico: as antigas
 //     vão para `_index/cerebro-archive.md`, seção `## Sessões antigas —
@@ -49,14 +50,31 @@ const hasCerebro = (dir) => {
 
 const expandHome = (p) => (p.startsWith('~') ? path.join(os.homedir(), p.slice(1)) : p);
 
+/** Pasta do Cérebro por projeto: `<output_folder>/cerebro/`, `_wizz-output` sem config. */
+function projectVault(root, configValues = {}) {
+  if (!root) return '';
+  const raw =
+    typeof configValues.output_folder === 'string' && configValues.output_folder.trim()
+      ? configValues.output_folder.trim()
+      : '_wizz-output';
+  const out = raw.replace(/^\{project-root\}[/\\]?/, '');
+  return path.join(path.isAbsolute(out) ? out : path.join(root, out), 'cerebro');
+}
+
 /**
- * Acha o vault: `WIZZ_CEREBRO_VAULT` > `cerebro_vault` do config > padrão do
- * protocolo no HOME. Só vale pasta com CEREBRO.md.
+ * Acha o vault: `WIZZ_CEREBRO_VAULT` > `cerebro_vault` do config > Cérebro por
+ * projeto em `root` > padrão do protocolo no HOME. Só vale pasta com CEREBRO.md.
  * @param {Record<string,string>} configValues
+ * @param {string} [root] raiz do projeto (habilita o Cérebro por projeto)
  * @returns {string} caminho do vault ou ''
  */
-function findVault(configValues = {}) {
-  const candidates = [process.env.WIZZ_CEREBRO_VAULT, configValues.cerebro_vault, path.join(os.homedir(), DEFAULT_VAULT)];
+function findVault(configValues = {}, root = '') {
+  const candidates = [
+    process.env.WIZZ_CEREBRO_VAULT,
+    configValues.cerebro_vault,
+    projectVault(root, configValues),
+    path.join(os.homedir(), DEFAULT_VAULT),
+  ];
   for (const c of candidates) {
     if (typeof c === 'string' && c.trim() && hasCerebro(expandHome(c.trim()))) return expandHome(c.trim());
   }
@@ -200,24 +218,29 @@ function writeArchive(vault, projeto, overflow, header) {
 /**
  * Grava o fechamento no arquivo do projeto no Cérebro. Fail-open: qualquer
  * falha devolve {gravado: false, motivo} sem lançar.
- * @param {{root: string, slug: string, status: string, projeto?: string}} input
+ * @param {{root: string, slug: string, status: string, projeto?: string, spec?: string}} input
+ *   `spec`: caminho da spec que o `encerrar` acabou de arquivar (sem ele, adivinha)
  * @returns {{gravado: boolean, arquivo?: string, motivo?: string}}
  */
-function recordClose({ root, slug, status, projeto }) {
+function recordClose({ root, slug, status, projeto, spec: knownSpec }) {
   try {
     const { values } = lib.readConfig(root);
-    const vault = findVault(values);
+    const vault = findVault(values, root);
     if (!vault) return { gravado: false, motivo: 'vault do Cérebro não encontrado (WIZZ_CEREBRO_VAULT)' };
     const file = findProjectFile(vault, root, values, projeto);
     if (!file) return { gravado: false, motivo: `sem projetos/<projeto>.md no vault (use --projeto <nome>)` };
 
     const date = lib.today();
     const dirs = lib.artifactDirs(root);
-    // O `encerrar` arquiva o sprint antes de chamar aqui: procura nas duas casas.
+    // O `encerrar` passa a spec que arquivou. Sem ela, a pasta aberta vem
+    // primeiro: num sprint reaberto a cópia de `_arquivo/` é o fechamento
+    // ANTERIOR, e o Cérebro gravava o resumo velho.
     const spec =
-      [path.join(dirs.planning, lib.ARCHIVE_DIR, slug), path.join(dirs.planning, slug)]
+      (knownSpec && fs.existsSync(knownSpec) && knownSpec) ||
+      [path.join(dirs.planning, slug), path.join(dirs.planning, lib.ARCHIVE_DIR, slug)]
         .map((d) => path.join(d, `spec-${slug}.md`))
-        .find((f) => fs.existsSync(f)) || path.join(dirs.planning, slug, `spec-${slug}.md`);
+        .find((f) => fs.existsSync(f)) ||
+      path.join(dirs.planning, slug, `spec-${slug}.md`);
     const specText = fs.existsSync(spec) ? fs.readFileSync(spec, 'utf8') : '';
     const specRel = path.relative(root, spec);
     const resumo = implementationSummary(specText);

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

@@ -399,9 +399,11 @@ const MD_LINK = /\]\((?!(?:[a-z][\w+.-]*:|#|\/))([^)\s#?]+)([^)\s]*)\)/gi;
  * @param {string} oldDir - pasta antiga do arquivo (absoluta)
  * @param {string} newDir - pasta nova do arquivo (absoluta)
  * @param {(abs: string) => string} [mapAbs] - caminho atual de um alvo movido
+ * @param {{onlyMoved?: boolean}} [opts] - só toca link cujo alvo `mapAbs` moveu
+ *   (arquivo que não sai do lugar: o resto dos links fica como o autor escreveu)
  * @returns {string}
  */
-function rebaseMarkdownLinks(text, oldDir, newDir, mapAbs = (p) => p) {
+function rebaseMarkdownLinks(text, oldDir, newDir, mapAbs = (p) => p, { onlyMoved = false } = {}) {
   return String(text).replaceAll(MD_LINK, (whole, target, rest) => {
     let decoded;
     try {
@@ -411,6 +413,7 @@ function rebaseMarkdownLinks(text, oldDir, newDir, mapAbs = (p) => p) {
     }
     const original = path.resolve(oldDir, decoded);
     const abs = mapAbs(original);
+    if (onlyMoved && abs === original) return whole;
     // Link que já não apontava para nada fica como está: reescrever inventaria outro caminho.
     if (!fs.existsSync(original) && !fs.existsSync(abs)) return whole;
     const next = path.relative(newDir, abs).split(path.sep).join('/') || '.';

package/tools/hooks/wizz-feature.js

@@ -16,7 +16,10 @@
 //   status <status>          rascunho|aprovado|implementado|no-ar na spec
 //   verificar                checklist de fechamento (exit 1 se houver pendência)
 //   encerrar                 status final na spec, arquiva o sprint em _arquivo/
-//                            (com o sprint-status.yaml da raiz), limpa/troca active_feature
+//                            (com o sprint-status.yaml da raiz quando é dele; o de
+//                            mesmo nome de um fechamento anterior vai para o lado;
+//                            falha no meio desfaz tudo; referências de fora corrigidas
+//                            ou listadas), limpa/troca active_feature
 //                            (recusa com pendência do checklist, salvo --forcar);
 //                            com --cerebro grava Estado + linha de Sessões no
 //                            projetos/<projeto>.md do Cérebro (--projeto <nome>)
@@ -29,6 +32,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const lib = require('./wizz-feature-lib.js');
 const cerebro = require('./wizz-cerebro-lib.js');
+const archive = require('./wizz-sprint-archive-lib.js');
 
 const ALIASES = {
   resolve: 'resolver',
@@ -61,6 +65,8 @@ function rel(root, p) {
   return path.relative(root, p) || '.';
 }
 
+const toPosixPath = (p) => p.split(path.sep).join('/');
+
 /** Pasta de cada tipo de artefato, para uma feature. */
 function artifactPath(root, type, slug, dirs = lib.artifactDirs(root)) {
   const where = lib.ARTIFACT_TYPES[type];
@@ -146,7 +152,10 @@ function cmdDefinir(state, opts) {
   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;
+  // O sprint aberto é o resolvido (branch > config), não só o do config: com o
+  // branch apontando outra feature o config velho recusava a certa, e o vazio
+  // deixava abrir uma que o branch esconderia (adendo de 2026-10-19).
+  const previous = state.slug;
   // O sprint aberto manda: assunto novo entra nele. Abrir outro sprint com um
   // aberto é escolha do dono, nunca do agente (pastas demais na Lucrare, 2026-10-15).
   if (previous && previous !== slug && !opts.novo) {
@@ -261,72 +270,6 @@ function looseArtifacts(root, dirs) {
   return out;
 }
 
-/** Move `src` para `dest`, mesclando quando `dest` já existe (sprint reaberto e fechado de novo). */
-function moveInto(src, dest) {
-  if (!fs.existsSync(dest)) {
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    fs.renameSync(src, dest);
-    return;
-  }
-  for (const name of fs.readdirSync(src)) moveInto(path.join(src, name), path.join(dest, name));
-  fs.rmdirSync(src);
-}
-
-function markdownFiles(dir) {
-  let entries = [];
-  try {
-    entries = fs.readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  return entries.flatMap((e) => {
-    const abs = path.join(dir, e.name);
-    if (e.isDirectory()) return markdownFiles(abs);
-    return e.isFile() && e.name.endsWith('.md') ? [abs] : [];
-  });
-}
-
-/**
- * Sprint fechado vai para o arquivo morto: as duas pastas da feature descem
- * para `_arquivo/<slug>/`, e o `sprint-status.yaml` da raiz de implementação
- * (o do sprint aberto) vai junto, para o próximo sprint começar limpo.
- * @returns {{planning: string, implementation: string, sprintStatus: string}}
- */
-function archiveSprint(root, slug) {
-  const dirs = lib.artifactDirs(root);
-  const out = {};
-  const moves = [dirs.planning, dirs.implementation].map((base) => ({
-    src: path.join(base, slug),
-    dest: path.join(base, lib.ARCHIVE_DIR, slug),
-  }));
-  const mapAbs = (abs) => {
-    const hit = moves.find((m) => abs === m.src || abs.startsWith(m.src + path.sep));
-    return hit ? hit.dest + abs.slice(hit.src.length) : abs;
-  };
-  // Links relativos (`../`) descem um nível junto com o arquivo: reescreve antes de mover.
-  for (const { src, dest } of moves) {
-    for (const file of markdownFiles(src)) {
-      const text = fs.readFileSync(file, 'utf8');
-      const next = lib.rebaseMarkdownLinks(text, path.dirname(file), path.dirname(mapAbs(file)), mapAbs);
-      if (next !== text) fs.writeFileSync(file, next);
-    }
-    if (fs.existsSync(src)) moveInto(src, dest);
-  }
-  out.planning = moves[0].dest;
-  out.implementation = moves[1].dest;
-  const status = path.join(dirs.implementation, 'sprint-status.yaml');
-  out.sprintStatus = '';
-  if (fs.existsSync(status)) {
-    const dest = path.join(out.implementation, 'sprint-status.yaml');
-    fs.mkdirSync(out.implementation, { recursive: true });
-    if (!fs.existsSync(dest)) {
-      fs.renameSync(status, dest);
-      out.sprintStatus = dest;
-    }
-  }
-  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.
@@ -390,9 +333,30 @@ function cmdVerificar(state, opts) {
 }
 
 /** `--cerebro`: grava no vault; fail-open, nunca desfaz o encerramento. */
-function cerebroClose(state, slug, status, opts) {
+function cerebroClose(state, slug, status, opts, spec) {
   const projeto = typeof opts.projeto === 'string' ? opts.projeto : '';
-  return cerebro.recordClose({ root: state.root, slug, status, projeto });
+  return cerebro.recordClose({ root: state.root, slug, status, projeto, spec });
+}
+
+/**
+ * Sprint fechado vai para o arquivo morto: as duas pastas da feature descem
+ * para `_arquivo/<slug>/` (mesclando com um fechamento anterior), com a spec
+ * já no status final e as referências corrigidas. Planeja antes, aplica com
+ * desfazer: falha no meio deixa o projeto como estava.
+ */
+function archiveSprint(state, slug, status) {
+  const spec = artifactPath(state.root, 'spec', slug);
+  const created = !fs.existsSync(spec) && ensureArtifact(state.root, 'spec', slug).created;
+  try {
+    const text = touch(lib.setFrontmatterField(fs.readFileSync(spec, 'utf8'), 'status', status));
+    const plan = archive.planArchive(state.root, slug, { edits: new Map([[spec, text]]) });
+    const { asides } = archive.applyArchive(plan);
+    return { plan, asides, spec: plan.moves[0].dest + spec.slice(plan.moves[0].src.length) };
+  } catch (error) {
+    // A spec criada aqui some junto: nada do encerrar fica para trás.
+    if (created && fs.existsSync(spec)) fs.unlinkSync(spec);
+    throw error;
+  }
 }
 
 function cmdEncerrar(state, opts) {
@@ -400,6 +364,15 @@ function cmdEncerrar(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('|')}.` };
+  // Rodar de novo num sprint já fechado não recria a spec nem mexe no arquivo morto.
+  if (archive.isArchived(state.root, slug)) {
+    if (state.fromConfig === slug) lib.writeConfigValue(state.root, 'active_feature', '');
+    return {
+      ok: true,
+      data: { feature: slug, status, ja_encerrado: true },
+      line: `Sprint ${slug} já estava encerrado em ${lib.ARCHIVE_DIR}/${slug}/: nada a fazer.`,
+    };
+  }
   // 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) {
@@ -410,9 +383,20 @@ function cmdEncerrar(state, opts) {
       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).`,
     };
   }
-  setSpecStatus(state, slug, status);
-  const archived = archiveSprint(state.root, slug);
-  const file = path.join(archived.planning, `spec-${slug}.md`);
+  let archived;
+  try {
+    archived = archiveSprint(state, slug, status);
+  } catch (error) {
+    const desfeito = error.desfeito === false ? 'O desfazer não fechou: confira o projeto.' : 'Desfiz o que tinha feito: nada mudou.';
+    return {
+      ok: false,
+      code: 1,
+      data: { feature: slug, erro: error.message },
+      line: `Não encerrei ${slug}: ${error.message}. ${desfeito}`,
+    };
+  }
+  const { plan } = archived;
+  const file = archived.spec;
   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) {
@@ -420,10 +404,14 @@ function cmdEncerrar(state, opts) {
     for (const d of [dirs.planning, dirs.implementation]) fs.mkdirSync(path.join(d, next), { recursive: true });
   }
   const parts = [`Sprint ${slug} encerrado (${status}) em ${lib.today()} e arquivado. Spec: ${rel(state.root, file)}.`];
-  if (archived.sprintStatus) parts.push(`sprint-status.yaml arquivado junto: o próximo sprint começa limpo.`);
+  if (plan.status?.owned) parts.push(`sprint-status.yaml arquivado junto: o próximo sprint começa limpo.`);
+  else if (plan.status) parts.push(`O sprint-status.yaml da raiz ficou na raiz (${plan.status.motivo}): mova à mão se for deste sprint.`);
+  if (archived.asides.length > 0)
+    parts.push(`Fechamento anterior preservado ao lado: ${archived.asides.map((a) => rel(state.root, a)).join(', ')}.`);
+  if (plan.externas.length > 0) parts.push(`Ainda citam a pasta antiga do sprint (corrija): ${plan.externas.map(toPosixPath).join(', ')}.`);
   parts.push(next ? `Sprint aberto agora: ${next}.` : 'Nenhum sprint aberto agora: o próximo pedido de trabalho abre um.');
   if (state.fromBranch === slug) parts.push(`O branch ${state.git.branch} ainda aponta para ${slug}: volte ao tronco ou troque de branch.`);
-  const memo = opts.cerebro ? cerebroClose(state, slug, status, opts) : null;
+  const memo = opts.cerebro ? cerebroClose(state, slug, status, opts, file) : null;
   if (memo && memo.gravado) parts.push(`Cérebro atualizado: ${memo.arquivo} (Estado + linha em Sessões).`);
   else {
     if (memo) parts.push(`Cérebro não gravado (${memo.motivo}).`);
@@ -435,7 +423,9 @@ function cmdEncerrar(state, opts) {
     status,
     proxima: next,
     pendencias: pend.map((p) => p.item),
-    arquivo: rel(state.root, archived.planning),
+    arquivo: rel(state.root, plan.moves[0].dest),
+    referencias_externas: plan.externas,
+    preservados: archived.asides.map((a) => rel(state.root, a)),
   };
   if (memo) data.cerebro = memo;
   return { ok: true, data, line: parts.join(' ') };