wizz-method 2.21.0 → 2.23.0

package/src/modules/wizz/_shared/organizacao.md

@@ -26,7 +26,7 @@ The SessionStart and UserPromptSubmit hooks already tell you the state (`FEATURE
 6. **Feature branch** (`feat/<slug>`) → the branch already is the sprint; when the config disagrees, `F definir <branch-slug> --novo`.
 7. **`feature_branches: auto`** in the config and you are on a trunk branch → propose `git switch -c feat/<slug>` in one line. With `off` (the default, for whoever works on `main`) say nothing about branches.
 
-**Closing archives.** `F encerrar` moves the sprint's two folders to `_arquivo/<slug>/` inside each artifact folder, together with the root `{implementation_artifacts}/sprint-status.yaml`, so the next sprint starts clean. `F listar` shows the open sprints and one line with the number of archived ones. The archive is history, not trash: when a request needs a past decision, spec or retro ("how did we solve the Meta sync?"), search `_arquivo/` of both artifact folders (and the Cérebro, which points to it) before saying it does not exist.
+**Closing archives.** `F encerrar` moves the sprint's two folders to `_arquivo/<slug>/` inside each artifact folder, together with the root `{implementation_artifacts}/sprint-status.yaml` when it belongs to that sprint (otherwise it stays and the output says why), so the next sprint starts clean. It plans before touching the disk and undoes everything on a failure; closing a reopened sprint keeps the previous close's same-named files beside the new ones as `<name>.anterior-<date>`. References from outside the sprint (CLAUDE.md, roteiros, design html) are rewritten; code and config that still cite the old folder are listed for you to fix. `F listar` shows the open sprints and one line with the number of archived ones. The archive is history, not trash: when a request needs a past decision, spec or retro ("how did we solve the Meta sync?"), search `_arquivo/` of both artifact folders (and the Cérebro, which points to it) before saying it does not exist.
 
 **Handoff:** every brief carries `feature: <slug>` (or `feature: nenhuma` for work that is not named). A receiver without that field resolves it itself with the steps above before writing anything; it never writes an artifact without a resolved feature.
 
@@ -61,7 +61,7 @@ Run `F verificar`. It checks the mechanical items and returns the judgment items
 - [ ] Spec exists, valid frontmatter, acceptance criteria filled.
 - [ ] `## Implementação` filled when the status is `implementado` or "no-ar".
 - [ ] Roteiro with Rollback in `{project_knowledge}/` when the status is "no-ar".
-- [ ] Cérebro: project state + one line in the Sessions table (`F encerrar --cerebro` writes both; vault from `WIZZ_CEREBRO_VAULT`, `cerebro_vault:` in the config or `~/Documents/projects/Obsidian Vault`; project file from `--projeto`, `project_name` or the folder name).
+- [ ] Cérebro: project state + one line in the Sessions table (`F encerrar --cerebro` writes both; vault found as in the `wizz-cerebro` skill, section `## Vault`; project file from `--projeto`, `project_name` or the folder name).
 - [ ] Auto-memory: only a reproducible trap or an owner preference (state and decisions belong to the Cérebro).
 
 A delivered feature (status `implementado` or "no-ar") with a pending item also triggers a Stop-hook warning (`wizz-close-reminder.js`) at the end of the turn.

package/src/modules/wizz/_shared/video-pipeline.md

@@ -29,6 +29,8 @@
 | **Source B-roll / inserts: find real footage of what the script names** | `get-brolls` (darwin) |
 | Edit/cut recorded footage (cuts, selects, roughcut) | `buttercut` (darwin-arm64 only) |
 | Analyze an existing reference video (frames + transcription) | `claude-video` |
+| One-take product film with the onetake skill itself, personal or noncommercial work only (client work needs onetake Pro) | `onetake` (opt-in; otherwise the one-take technique in `wizz-video-effects` runs in this pipeline) |
+| Hand-painted cartoon where Claude itself appears (Clawd, p5.brush), for content about Claude/Claude Code/Wizz | `claude-animation-base` (clone-and-run; renders an MP4 that enters Remotion as a clip) |
 | AI-generated video/image (Veo/Kling/Wan), UGC / ad-ready style | `wizz-ad-creative` (ads area) writes the prompt; the user generates it in Flow or another AI tool, outside the method |
 
 ## Full chain (script → publishing)

package/src/modules/wizz/agents/wizz-copy/SKILL.md

@@ -25,6 +25,7 @@ You are Wizz's Copy. It writes texts that sell, humanizes what sounds robotic, a
 - Email, sequence, nurture → `wizz-email-sequence`
 - Make text natural, remove the AI feel → `wizz-humanizer`
 - Review/edit existing text → `wizz-copy-editing`
+- VSL (video sales letter) script, from the expert interview to a script ready to record plus the production beat sheet → `wizz-vsl`; under low ticket it reads the methodology's VSL ruler first
 
 Always deliver 2-3 variations and say which one you recommend.
 

package/src/modules/wizz/agents/wizz-copy/customize.toml

@@ -40,6 +40,11 @@ code = "PG"
 description = "Page copy, headline, value proposition, CTA"
 prompt = "Invoke the GLOBAL skill 'wizz-copywriting' via the Skill tool. Then run the 'wizz-humanizer' logic on the final text. Deliver 2-3 variations in easy {communication_language}."
 
+[[agent.menu]]
+code = "VSL"
+description = "VSL script: interview, mechanisms, offer, leads, beat sheet"
+prompt = "Invoke the GLOBAL skill 'wizz-vsl' via the Skill tool. It resumes from its manifest when one exists, reuses an approved wizz-offer-forge offer and the audience research, and hands production (narration, wizz-ctc-align, hyperframes, Remotion) to the designer area: offer wizz-maestro when the user wants the video in the same delivery."
+
 [[agent.menu]]
 code = "EM"
 description = "Email, nurture sequence, follow-up"

package/src/modules/wizz/agents/wizz-copy/knowledge/playbook.md

@@ -4,19 +4,20 @@
 
 ## Ordem base (declarada no registry)
 
-`wizz-pesquisa-de-publico-do-piva` e `wizz-offer-forge` vêm antes de `wizz-copywriting`; `wizz-copy-editing` vem depois. Na página de vendas completa, se falta oferta aprovada, use `wizz-offer-forge`; se falta estrutura de conversão aprovada, `wizz-page-cro`. Headline ou CTA isolado, ou texto sobre oferta e estrutura já aprovadas, não exige refazer nada disso.
+`wizz-pesquisa-de-publico` e `wizz-offer-forge` vêm antes de `wizz-copywriting`; `wizz-copy-editing` vem depois. Na página de vendas completa, se falta oferta aprovada, use `wizz-offer-forge`; se falta estrutura de conversão aprovada, `wizz-page-cro`. Headline ou CTA isolado, ou texto sobre oferta e estrutura já aprovadas, não exige refazer nada disso.
 
 ## Situações
 
 | Situação                                              | Skill (nesta ordem)                        | Onde olhar                                                                                           |
 | ----------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
-| Não conheço o público, as dores, a linguagem          | `wizz-pesquisa-de-publico-do-piva`              | `wizz-pesquisa-de-publico-do-piva/SKILL.md`                                                               |
+| Não conheço o público, as dores, a linguagem          | `wizz-pesquisa-de-publico`                 | `wizz-pesquisa-de-publico/SKILL.md`                                                                  |
 | Não há oferta definida                                | `wizz-offer-forge`                         | `wizz-offer-forge/references/mecanismo-unico.md`, `empilhamento-valor.md`, `garantia-reversa.md`     |
 | Copy de venda, página ou headline do zero             | `wizz-copywriting`                         | `wizz-copywriting/references/copy-frameworks.md`, `natural-transitions.md`                           |
 | Texto já existe e precisa melhorar                    | `wizz-copy-editing`                        | `wizz-copy-editing/references/plain-english-alternatives.md`                                         |
 | Texto soa feito por IA                                | `wizz-humanizer`                           | `wizz-humanizer/references/ai-writing-patterns.md`                                                   |
 | Sequência de e-mail (onboarding, nurture, lançamento) | `wizz-email-sequence`                      | `references/email-types.md`, `sequence-templates.md`, `copy-guidelines.md`                           |
 | Cold email, outbound B2B                              | `wizz-cold-email`                          | `references/frameworks.md`, `subject-lines.md`, `personalization.md`, `follow-up-sequences.md`       |
+| Roteiro de VSL (vídeo de vendas)                      | `wizz-vsl`                                 | `wizz-vsl/SKILL.md` (no low ticket lê antes a régua de VSL da `wizz-lowticket-metodologia`)          |
 | Deck, one-pager, objeções, demo                       | `wizz-sales-enablement`                    | `references/deck-frameworks.md`, `objection-library.md`, `demo-scripts.md`, `one-pager-templates.md` |
 | Copy de low ticket BR/PT                              | `wizz-lowticket-metodologia` (área growth) | `wizz-lowticket-metodologia/knowledge/18-copy-desejo-oferta.md`, `07a-copy-humanizacao.md`           |
 | Texto para anúncio                                    | `wizz-ad-creative` (área ads)              | `wizz-paid-ads/references/ad-copy-templates.md`                                                      |

package/src/modules/wizz/agents/wizz-growth/customize.toml

@@ -63,8 +63,8 @@ prompt = "Invoke the GLOBAL skill 'wizz-churn-prevention' via the Skill tool."
 
 [[agent.menu]]
 code = "PV"
-description = "Audience research, VoC, and angle matrix (Piva)"
-prompt = "Invoke the GLOBAL skill 'wizz-pesquisa-de-publico-do-piva' via the Skill tool. Ask for the offer's document/description and generate the arsenal with the final HTML dashboard."
+description = "Audience research, VoC, and angle matrix"
+prompt = "Invoke the GLOBAL skill 'wizz-pesquisa-de-publico' via the Skill tool. Ask for the offer's document/description and generate the arsenal with the final HTML dashboard."
 
 [[agent.menu]]
 code = "OF"
@@ -101,6 +101,11 @@ code = "LP"
 description = "Low ticket: sales page performance (connect rate, pixel order, LCP)"
 prompt = "Invoke the lowticket module skill 'wizz-lowticket-pagina' via the Skill tool. It engineers performance; it doesn't rewrite copy, price or offer."
 
+[[agent.menu]]
+code = "LC"
+description = "Low ticket: clone the expert's voice into a GPT/Project for students"
+prompt = "Invoke the lowticket module skill 'wizz-clone-do-expert' via the Skill tool. It needs the expert's real material (lives, audios, posts) or runs a short interview. Persona research is 'wizz-pesquisa-de-publico', not this."
+
 [[agent.menu]]
 code = "AB"
 description = "Set up an A/B test or conversion experiment"

package/src/modules/wizz/agents/wizz-growth/knowledge/playbook.md

@@ -8,8 +8,8 @@
 | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
 | Travou, não sabe o canal                       | `wizz-marketing-ideas`                                                                                       | `wizz-marketing-ideas/references/ideas-by-category.md`                                                                                   |
 | Posicionamento e contexto do produto           | `wizz-product-marketing-context`, `wizz-marketing-psychology`                                                | `SKILL.md` de cada uma                                                                                                                   |
-| Entender o público                             | `wizz-pesquisa-de-publico-do-piva`                                                                                | `SKILL.md`                                                                                                                               |
-| Criar ou refazer oferta                        | `wizz-pesquisa-de-publico-do-piva`, depois `wizz-offer-forge`                                                     | `wizz-offer-forge/references/` (mecanismo, empilhamento, garantia, ponte de tráfego, plano de medição)                                   |
+| Entender o público                             | `wizz-pesquisa-de-publico`                                                                                | `SKILL.md`                                                                                                                               |
+| Criar ou refazer oferta                        | `wizz-pesquisa-de-publico`, depois `wizz-offer-forge`                                                     | `wizz-offer-forge/references/` (mecanismo, empilhamento, garantia, ponte de tráfego, plano de medição)                                   |
 | Lançamento de produto ou feature               | `wizz-launch-strategy`, com `wizz-email-sequence`                                                            | `references/five-phase-approach.md`, `launch-checklist.md`, `orb-framework.md`, `product-hunt-strategy.md`, `post-launch-and-ongoing.md` |
 | Preço, planos, packaging                       | `wizz-pricing-strategy`                                                                                      | `references/tier-structure.md`, `research-methods.md`                                                                                    |
 | Churn, cancelamento, cobrança que falha        | `wizz-churn-prevention`                                                                                      | `references/cancel-flow-patterns.md`, `dunning-playbook.md`                                                                              |
@@ -32,6 +32,7 @@ Quem não sabe por onde começar entra por `wizz-lowticket-guia`, que vem antes
 | Performance da página de venda                                                                    | `wizz-lowticket-pagina`             | vem antes de `wizz-lowticket-funil`                                 |
 | Escada pós-checkout                                                                               | `wizz-lowticket-funil`              | só depois de existir front-end que converte                         |
 | Campanha Meta                                                                                     | `wizz-lowticket-trafego` (área ads) | via `wizz-ads`                                                      |
+| Clone da voz do expert (GPT/Project pros alunos)                                                  | `wizz-clone-do-expert`              | persona de quem compra é `wizz-pesquisa-de-publico`                 |
 
 ## Limites
 

package/src/modules/wizz/agents/wizz-social/knowledge/blueprint-roteiro-viral.md

@@ -50,6 +50,20 @@ Requires speed: must go out the same day or within 24h. Once the window passes,
 
 **Fundamental pattern:** every hook exists between two poles, **provocation** (you're wrong / your profession is ending) and **promise** (I discovered something you need to know). The strongest ones trigger both at once.
 
+### Hook pre-check (before shooting)
+
+Write **three** hooks of different types, not three rewordings of one, and for each write the spoken line and the on-screen line separately (on screen is the shorter, blunter one, six words or fewer). Then score each spoken line from 0 to 100 on five checks and keep the best:
+
+| Check | Strong when | Weak when |
+|---|---|---|
+| Length | 5 to 12 words, sayable in under 3 seconds | a preamble, or a sentence that needs a breath |
+| Specificity | a concrete marker: a number, a name, a tool, a place | "muita coisa", "um monte de tempo" |
+| Stakes | something is won, lost or at risk in the line | nothing is at stake |
+| Front-loading | the interesting word in the first two or three | "oi gente", "hoje eu vou", "então" opening |
+| Address | aimed at a viewer ("você", a role, a situation) | aimed at nobody |
+
+A hook whose weakest check is low is rewritten on that check before anything else. The score catches greetings, preambles and empty hooks; it does not predict which of two decent hooks will travel (the face, the edit, the audio and the distribution decide that): trust the retention graph over the score. Never invent the number a hook needs: it comes from the user or stays a slot. *(Adapted from the hook checks of Jakeschincariol/instagram-agent-skill, MIT, credited in `THIRD-PARTY-NOTICES.md`.)*
+
 ---
 
 ## 2. Narrative Structure

package/src/modules/wizz/agents/wizz-social/knowledge/legenda-instagram.md

@@ -39,6 +39,18 @@ Supporting knowledge for **wizz-social** (Rafa). Creates the optimized descripti
 - **Fast Reels / simple feed post:** 80 to 150 characters (short, direct, impactful).
 - **Educational carousel / storytelling:** 300 to 800 characters (delivers value, increases reading time).
 
+## The fold check (before delivering)
+
+Instagram shows about **125 characters** before "mais". Check the caption the way the feed prints it:
+
+- **Decide the job first.** Reel: the video already hooked the viewer, so line one carries the ask and the context, not a second hook competing with the video. Photo, single image or carousel cover: the caption is the content, so line one is the hook and it ends at a cliff, not mid-clause.
+- Line one fits inside the 125 characters: never a greeting, a hashtag or an emoji as the first character.
+- **One ask** only (comment a keyword, save, or DM). A keyword ask uses one typable word with no spaces or emoji, also said in the video.
+- No link in the caption: captions are not clickable; the link goes in the bio, a DM, or the first comment.
+- The phrases the user wants to be found for go in the body as a human would type them; hashtags (up to 5) are labels, not reach.
+
+Add one line under the caption in the delivery: `👁️ Antes do "mais": N/125 caracteres`. *(Adapted from the caption linter of Jakeschincariol/instagram-agent-skill, MIT, credited in `THIRD-PARTY-NOTICES.md`.)*
+
 ## General rules
 - Never robotic or generic. Write like a human.
 - Emojis with moderation and purpose: they guide the eye, they don't clutter.

package/src/skills-lib/wizz-cerebro/SKILL.md

@@ -53,12 +53,25 @@ Read offset=(line-5) limit=15        # → reads only the needed excerpt
 
 ## Vault
 
-Known default vault: `~/Documents/projects/Obsidian Vault/`
+This section is the **single source** of vault discovery. Every other file (command references, `_shared/cerebro.md`) points here instead of repeating it. The vault is plain markdown: it works with or without the Obsidian app.
 
-**How to discover it:**
-1. Try `~/Documents/projects/Obsidian Vault/CEREBRO.md` — if it exists, use it.
-2. If not: `find ~ -name "CEREBRO.md" -maxdepth 6 2>/dev/null | head -1`
-3. If still nothing: ask the user.
+**How to discover it** (first folder that holds a `CEREBRO.md` wins; `wizz-feature.js encerrar --cerebro` reads steps 1 to 3 in the same order):
+1. `$WIZZ_CEREBRO_VAULT`, then `cerebro_vault:` in `_wizz/bmm/config.yaml`.
+2. Per-project Cérebro of the current repo: `_wizz-output/cerebro/` (or `{output_folder}/cerebro/` when the config sets another output folder).
+3. Global default: `~/Documents/projects/Obsidian Vault/`.
+4. `find ~ -maxdepth 6 -name "CEREBRO.md" -not -path "*/_wizz-output/*" 2>/dev/null | head -1` (skips other repos' per-project Cérebros).
+
+**Nothing found.** A read-only command (`/ver`, `/dia`, `/memoria`) says there is no Cérebro yet and stops. A command that saves (`/iniciar`, `/salvar`, `/dump`, `/decisao`, `/conteudo`, `/prospect`) never writes to an invented place in silence: ask once (AskUserQuestion where available, a numbered question otherwise):
+- **Global Cérebro** (one for every project): then ask which folder, suggesting `~/Documents/projects/Obsidian Vault/`. Outside the default path, tell the user that `export WIZZ_CEREBRO_VAULT="<folder>"` in the shell profile lets the CLI find it too (do not edit the profile yourself).
+- **Per-project Cérebro** (inside this repo, at `_wizz-output/cerebro/`): then ask once whether it stays out of git (private: append `_wizz-output/cerebro/` to `.gitignore`) or is committed (shared with the team).
+
+**After the choice**, create the minimal structure and never ask again (the next discovery finds it):
+```
+<vault>/CEREBRO.md      first line: vault: <absolute path>   (per-project adds a second line: scope: project)
+<vault>/projetos/
+<vault>/_decisions/
+```
+A per-project Cérebro needs no config entry: the feature-closing CLI finds `_wizz-output/cerebro/` by itself, so no machine path lands in a committed config. Then continue the command that triggered the question.
 
 **Never Read the entire CEREBRO.md just to find the vault path** — use grep:
 ```bash

package/src/skills-lib/wizz-design-needs/SKILL.md

@@ -49,6 +49,13 @@ Both read `design-state.yaml`, take the need's `budget` and `floor` as given, an
 
 Level 4 or 5 also hands off to `wizz-motion-3d-director` before any behaviour need is mined.
 
+## Executable checks on the map
+
+`scripts/design_state.py` (run with `uv run --no-cache`) reads the rubric and the level ceiling from the skill files and checks the map itself, so the gates are not only prose:
+
+- `validate {output_folder}/design-state.yaml`: statuses and required reasons, verdict against the score band, entry conditions, the cut and each need's floor, one signature per surface, dedup links, the adaptation on every selected discovery, and the behaviour ceiling of the level. The miners run it after writing discoveries; findings are fixed in the map before the handoff.
+- `gate {output_folder}/design-state.yaml --section <surface>/<section>` (or `--need <id>`): the implementer runs it before building a non-trivial section, component or behaviour. Exit 0 passes (selected with a discovery, `unmet` with the research as the justification, `deferred` meaning "not now", `dropped`); exit 1 blocks an open need (mine it first) or a section the map does not know (`unplanned`, back to this skill). No map, no gate: the fail-open contract of the state file holds.
+
 ## References map (read on demand)
 
 | For... | Read |

package/src/skills-lib/wizz-design-needs/references/design-state.md

@@ -23,6 +23,8 @@ Read contract, deliberately identical to the one the router and the maestro alre
 | `implementacao` | `wizz-agent-dev` / `wizz-quick-dev` | QA |
 | `problemas` | QA, the audit protocol, the user | `wizz-design-needs` when reopening a need |
 
+`scripts/design_state.py validate` checks this contract and the rubric on a real file; `gate` is the implementer's check before building (both in the skill's SKILL.md).
+
 No block has two owners. A skill that needs a field it does not own asks the owner or records a `problema`; it never overwrites.
 
 ## Schema
@@ -70,13 +72,41 @@ needs:
     adaptive: { mobile: null, reduced_motion: null }   # obrigatório antes de fechar
     status: open                  # open | mining | evaluated | selected | unmet | dropped | deferred
     reason: null                  # obrigatório em dropped, deferred, unmet
-    satisfied_by: []
+    spent: { fontes: 0, secas: 0 }   # escrito pelo minerador: fontes abertas, fontes seguidas sem nada elegível
+    satisfied_by: []              # ids das discoveries selecionadas
 
 proibidos:
   - { o_que: "partícula, glow, gradiente saturado, 3D", por: sinal:minimalista }
   - { o_que: "carrossel de logos, card de depoimento genérico", por: tipo:autoridade }
 
-discoveries: []      # escrito pelo minerador
+discoveries:         # escrito pelo minerador; regras em mining-rubric.md
+  - id: disc-001
+    need: b1-hero-entrada         # toda descoberta responde a uma necessidade
+    surface: home
+    layer: comportamento          # copiado da need: o teto de comportamento é contado por superfície
+    source:
+      url: "https://..."
+      kind: code                  # code | registry | visual
+      revision: "a3f1c9d"         # SHA, tag ou data de leitura
+      license: MIT                # null quando não há
+      access: publico             # publico | cache | fornecido_pelo_usuario | pago_autorizado
+    evidence: verified            # verified | unverified (gate de web-access-and-evidence.md)
+    pattern: "revelação por máscara vertical sincronizada com o scroll"
+    pattern_key: scroll-mask-reveal   # chave de dedup dentro do projeto
+    observed: ["máscara 420ms, cubic-bezier(.2,.8,.2,1)", "sem useReducedMotion no código"]
+    inferred: ["provavelmente usa GSAP ScrollTrigger"]
+    disqualifiers: []             # códigos de condição de entrada não cumprida; qualquer um = DESCARTAR
+    scores: { aderencia: 3, execucao: 2, custo_adaptacao: 2, custo_performance: 1, originalidade: 1, total: 9 }
+    verdict: ASSINATURA           # ASSINATURA | FORTE | UTILITARIO | DESCARTAR
+    adaptation:                   # obrigatório quando selected
+      padrao: "o título é revelado por uma máscara que sobe com o scroll"
+      por_que: "segura o olho no título antes de liberar o corpo"
+      invariante: "a máscara tem que andar mais rápido que o scroll, senão lê como lag"
+      variavel: [easing, duração, direção, cor]
+      reimplementacao: "reimplementar com os tokens do projeto, sem copiar seletor nem classe"
+    status: selected              # proposed | selected | rejected | implemented | reverted
+    reason: null                  # obrigatório em rejected e reverted
+    dup_of: null                  # id da discovery selecionada que já resolve este padrão
 implementacao: {}    # escrito pelo dev
 problemas: []        # escrito pelo QA
 ```
@@ -97,6 +127,8 @@ open ──▶ mining ──▶ evaluated ──▶ selected ──▶ (implemen
   └──▶ deferred  (perdeu para o teto do nível)
 ```
 
+Discoveries have their own lifecycle: `proposed → selected → implemented`, or `rejected` / `reverted` with a `reason`. How a discovery is scored, when it is selected and when the miner stops are in [mining-rubric](../../wizz-premium-landing-ui-researcher/references/mining-rubric.md).
+
 `unmet`, `dropped` and `deferred` require a `reason`. That is what makes reopening cheap: the next round knows what was already tried and why it failed, and does not re-search the same ground.
 
 ## Reopening

package/src/skills-lib/wizz-design-needs/references/gap-analysis.md

@@ -24,7 +24,7 @@ When the layers disagree or the coverage cannot be proven by reading (a CSS rule
 - a site the user named as a reference: at the **system** layer (palette, type scale, spacing, radius), extract it instead of describing it, `npx -y dembrandt@0.39.2 <url> --design-md`, and close the need against the measured tokens
 - a Figma file from the client, through the Framelink MCP when the user set it up (see [component-sources](../../wizz-premium-landing-ui-researcher/references/component-sources.md))
 
-Cache freshness rule: check the revision and date before treating a cached item as current. A stale cache is still a valid source for a pattern; it is not a valid source for an API. When the cache answers a need, record the revision in the discovery, not just the path. For registry sources, the live index (`https://ui.shadcn.com/r/registries.json`, `health` per registry) is the freshness check: it costs one request and needs no clone.
+Cache freshness rule: check the revision and date before treating a cached item as current (`uv run --no-cache ../wizz-premium-landing-ui-researcher/scripts/design_sources.py freshness` from this skill's folder answers it for every cached clone). A stale cache is still a valid source for a pattern; it is not a valid source for an API. When the cache answers a need, record the revision in the discovery, not just the path. For registry sources, the live index (`https://ui.shadcn.com/r/registries.json`, `health` per registry) is the freshness check: it costs one request and needs no clone.
 
 User-supplied material outranks every catalogue. A reference the user chose is worth more than a better reference they did not.
 

package/src/skills-lib/wizz-design-needs/scripts/design_state.py

@@ -0,0 +1,305 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["ruamel.yaml>=0.18"]
+# ///
+"""Check design-state.yaml against the mining rubric, and gate implementation.
+
+Prints ONLY JSON to stdout.
+
+Subcommands:
+  validate <state>   Structural and rubric checks on needs and discoveries:
+                     statuses, required reasons, verdict vs score band, entry
+                     conditions, the cut and the need's floor, one signature per
+                     surface, dedup links, adaptation on selected discoveries,
+                     and the behaviour ceiling of the level. Exit 0 when ok,
+                     1 when there are findings, 2 on a file it cannot read.
+  gate <state> --section <surface>/<section> [--section ...] | --need <id>
+                     The implementer's gate. Before building a non-trivial
+                     section, component or behaviour, every need of that
+                     section must be in a terminal status, and each `selected`
+                     need must point at a selected discovery. Open, mining or
+                     evaluated needs block (mine first); a section the map does
+                     not know blocks as `unplanned` (back to wizz-design-needs).
+                     `unmet` passes (build from scratch, the research is the
+                     justification) and `deferred` passes with "do not build
+                     this behaviour now". Exit 0 pass, 1 blocked, 2 error.
+
+The numbers (cut, bands, entry-condition codes) are read from the
+`# mining-rubric:v1` block of mining-rubric.md and the behaviour ceiling from
+the Rule 3 table of derivacao.md. Nothing is restated here.
+
+Run with `uv run --no-cache scripts/design_state.py ...`.
+"""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+SKILLS = HERE.parents[1]
+DERIVATION = HERE.parent / "references" / "derivacao.md"
+RUBRIC_CANDIDATES = [
+    SKILLS / "wizz-premium-landing-ui-researcher" / "references" / "mining-rubric.md",
+]
+
+NEED_STATUSES = {"open", "mining", "evaluated", "selected", "unmet", "dropped", "deferred"}
+NEED_TERMINAL = {"selected", "unmet", "dropped", "deferred"}
+NEED_NEEDS_REASON = {"unmet", "dropped", "deferred"}
+DISC_STATUSES = {"proposed", "selected", "rejected", "implemented", "reverted"}
+DISC_NEEDS_REASON = {"rejected", "reverted"}
+DISC_CHOSEN = {"selected", "implemented"}
+ADAPTATION_FIELDS = ("padrao", "por_que", "invariante", "variavel", "reimplementacao")
+
+
+def emit(payload, code):
+    print(json.dumps(payload, ensure_ascii=False, indent=2, default=str))
+    sys.exit(code)
+
+
+def yaml_loader():
+    from ruamel.yaml import YAML
+
+    return YAML(typ="safe")
+
+
+def load_rubric(candidates=None):
+    for path in candidates or RUBRIC_CANDIDATES:
+        if path.exists():
+            text = path.read_text(encoding="utf-8")
+            match = re.search(r"```yaml\n(# mining-rubric:v1\n.*?)```", text, re.S)
+            if not match:
+                raise ValueError(f"{path}: no '# mining-rubric:v1' block")
+            return yaml_loader().load(match.group(1))
+    raise ValueError("mining-rubric.md not found next to this skill")
+
+
+def load_ceiling(path=DERIVATION):
+    text = path.read_text(encoding="utf-8")
+    start = text.index("## Rule 3")
+    section = text[start : text.find("\n## ", start + 1)]
+    ceiling = {}
+    for line in section.splitlines():
+        cells = [cell.strip() for cell in line.strip().strip("|").split("|")]
+        if len(cells) >= 3:
+            level, needs = re.match(r"\d+", cells[0]), re.match(r"\d+", cells[2])
+            if level and needs:
+                ceiling[int(level.group())] = int(needs.group())
+    if len(ceiling) < 5:
+        raise ValueError(f"{path}: Rule 3 table does not have the 5 levels")
+    return ceiling
+
+
+def load_state(path):
+    with open(path, encoding="utf-8") as handle:
+        data = yaml_loader().load(handle)
+    if not isinstance(data, dict):
+        raise ValueError(f"{path}: not a mapping")
+    return data
+
+
+def band(rubric, total):
+    for verdict in rubric["verdicts"]:
+        if verdict["min"] <= total <= verdict["max"]:
+            return verdict["id"]
+    return None
+
+
+class Findings:
+    def __init__(self):
+        self.items = []
+
+    def add(self, code, where, message):
+        self.items.append({"code": code, "where": where, "message": message})
+
+
+def check_needs(needs, out):
+    seen = set()
+    for need in needs:
+        nid = need.get("id")
+        if not nid or nid in seen:
+            out.add("need_id", str(nid), "need without id or with a duplicate id")
+        seen.add(nid)
+        status = need.get("status")
+        if status not in NEED_STATUSES:
+            out.add("need_status", str(nid), f"unknown status {status!r}")
+        if status in NEED_NEEDS_REASON and not need.get("reason"):
+            out.add("need_reason", str(nid), f"status {status} needs a reason")
+        if not need.get("why"):
+            out.add("need_why", str(nid), "a need without `why` does not trace to the brief")
+
+
+def check_scores(disc, rubric, out, where):
+    scores = disc.get("scores") or {}
+    total = 0
+    for criterion, (low, high) in rubric["criteria"].items():
+        value = scores.get(criterion)
+        if not isinstance(value, int) or not low <= value <= high:
+            out.add("score_range", where, f"{criterion}={value!r} outside {low}-{high}")
+            return None
+        total += value
+    if scores.get("total") not in (None, total):
+        out.add("score_total", where, f"total {scores.get('total')} != sum {total}")
+    return total
+
+
+def check_verdict(disc, rubric, out, where):
+    verdict = disc.get("verdict")
+    if disc.get("disqualifiers"):
+        unknown = set(disc["disqualifiers"]) - set(rubric["disqualifiers"])
+        if unknown:
+            out.add("disqualifier_code", where, f"unknown entry-condition codes {sorted(unknown)}")
+        if verdict != "DESCARTAR":
+            out.add("verdict_band", where, "an unmet entry condition means DESCARTAR")
+        return None
+    if disc.get("evidence") != "verified" or disc.get("dup_of"):
+        return None
+    total = check_scores(disc, rubric, out, where)
+    if total is None:
+        return None
+    expected = band(rubric, total)
+    capped = verdict == "FORTE" and expected == "ASSINATURA" and disc.get("reason") == rubric.get("signature_cap_reason")
+    if verdict != expected and not capped:
+        out.add("verdict_band", where, f"score {total} is {expected}, recorded {verdict}")
+    return total
+
+
+def check_chosen(disc, need, total, rubric, out, where):
+    if disc.get("evidence") != "verified":
+        out.add("selected_unverified", where, "an unverified discovery cannot be selected")
+    if disc.get("verdict") == "DESCARTAR" or disc.get("disqualifiers"):
+        out.add("selected_discarded", where, "a DESCARTAR discovery cannot be selected")
+    floor = max(rubric["cut"], int((need or {}).get("floor") or 0))
+    if total is not None and total < floor:
+        out.add("selected_below_floor", where, f"score {total} below the floor {floor}")
+    adaptation = disc.get("adaptation") or {}
+    missing = [field for field in ADAPTATION_FIELDS if not adaptation.get(field)]
+    if missing:
+        out.add("adaptation_missing", where, f"selected without adaptation fields {missing}")
+
+
+def check_discoveries(state, rubric, ceiling, out):
+    needs = {need.get("id"): need for need in state.get("needs") or []}
+    discoveries = state.get("discoveries") or []
+    by_id = {disc.get("id"): disc for disc in discoveries}
+    signatures, behaviours = {}, {}
+    for disc in discoveries:
+        where = str(disc.get("id"))
+        need = needs.get(disc.get("need"))
+        if need is None:
+            out.add("discovery_need", where, f"need {disc.get('need')!r} is not in the map")
+        status = disc.get("status")
+        if status not in DISC_STATUSES:
+            out.add("discovery_status", where, f"unknown status {status!r}")
+        if status in DISC_NEEDS_REASON and not disc.get("reason"):
+            out.add("discovery_reason", where, f"status {status} needs a reason")
+        if not disc.get("observed"):
+            out.add("observed_missing", where, "no `observed` list: a score must rest on what was seen")
+        if disc.get("dup_of"):
+            original = by_id.get(disc["dup_of"])
+            if not original or original.get("status") not in DISC_CHOSEN or original.get("pattern_key") != disc.get("pattern_key"):
+                out.add("dup_of", where, "dup_of must point at a selected discovery with the same pattern_key")
+        total = check_verdict(disc, rubric, out, where)
+        if status in DISC_CHOSEN:
+            check_chosen(disc, need, total, rubric, out, where)
+            surface = disc.get("surface") or (need or {}).get("surface")
+            if disc.get("verdict") == "ASSINATURA":
+                signatures[surface] = signatures.get(surface, 0) + 1
+            if (disc.get("layer") or (need or {}).get("layer")) == "comportamento":
+                behaviours[surface] = behaviours.get(surface, 0) + 1
+    limit = rubric.get("signature_per_surface", 1)
+    for surface, count in signatures.items():
+        if count > limit:
+            out.add("signature_cap", str(surface), f"{count} ASSINATURA selected, limit {limit}")
+    level = state.get("nivel")
+    if isinstance(level, int) and level in ceiling:
+        for surface, count in behaviours.items():
+            if count > ceiling[level]:
+                out.add("behaviour_ceiling", str(surface), f"{count} behaviours selected, level {level} allows {ceiling[level]}")
+    for need in needs.values():
+        if need.get("status") == "selected":
+            linked = [by_id.get(ref) for ref in need.get("satisfied_by") or []]
+            if not any(disc and disc.get("status") in DISC_CHOSEN for disc in linked):
+                out.add("need_unlinked", str(need.get("id")), "selected need without a selected discovery in satisfied_by")
+
+
+def validate(state, rubric, ceiling):
+    out = Findings()
+    check_needs(state.get("needs") or [], out)
+    check_discoveries(state, rubric, ceiling, out)
+    return out.items
+
+
+def gate(state, sections, need_ids):
+    needs = state.get("needs") or []
+    discoveries = {disc.get("id"): disc for disc in state.get("discoveries") or []}
+    targets = []
+    for ref in sections:
+        surface, _, section = ref.partition("/")
+        matched = [n for n in needs if n.get("surface") == surface and (not section or n.get("section") == section)]
+        targets.append((ref, matched))
+    for nid in need_ids:
+        targets.append((nid, [n for n in needs if n.get("id") == nid]))
+    results, blocked = [], False
+    for ref, matched in targets:
+        if not matched:
+            results.append({"target": ref, "result": "unplanned", "action": "not in the map: back to wizz-design-needs"})
+            blocked = True
+            continue
+        for need in matched:
+            row = {"target": ref, "need": need.get("id"), "status": need.get("status")}
+            status = need.get("status")
+            if status not in NEED_TERMINAL:
+                row.update(result="blocked", action="mine this need first (wizz-ui-component-curator / researcher)")
+                blocked = True
+            elif status == "selected":
+                chosen = [discoveries.get(ref_id) for ref_id in need.get("satisfied_by") or []]
+                chosen = [disc for disc in chosen if disc and disc.get("status") in {"selected", "implemented"}]
+                if chosen:
+                    row.update(result="pass", discoveries=[disc.get("id") for disc in chosen])
+                else:
+                    row.update(result="blocked", action="selected need without a selected discovery")
+                    blocked = True
+            elif status == "deferred":
+                row.update(result="pass", action="deferred by the level: do not build this behaviour now")
+            elif status == "unmet":
+                row.update(result="pass", action="unmet: build from scratch, cite the research as the justification")
+            else:
+                row.update(result="pass", action=need.get("reason") or "dropped")
+            results.append(row)
+    return blocked, results
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="design_state.py")
+    sub = parser.add_subparsers(dest="command", required=True)
+    check = sub.add_parser("validate")
+    check.add_argument("state")
+    gating = sub.add_parser("gate")
+    gating.add_argument("state")
+    gating.add_argument("--section", action="append", default=[])
+    gating.add_argument("--need", action="append", default=[])
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as error:
+        emit({"error": "invalid arguments"}, int(error.code or 2))
+    try:
+        state = load_state(args.state)
+        if args.command == "validate":
+            rubric, ceiling = load_rubric(), load_ceiling()
+    except (OSError, ValueError, ImportError) as error:
+        emit({"error": str(error)}, 2)
+    except Exception as error:  # ruamel parse errors have their own hierarchy
+        emit({"error": f"cannot parse: {error}"}, 2)
+    if args.command == "validate":
+        findings = validate(state, rubric, ceiling)
+        emit({"ok": not findings, "findings": findings}, 1 if findings else 0)
+    if not args.section and not args.need:
+        emit({"error": "gate needs --section <surface>/<section> or --need <id>"}, 2)
+    blocked, results = gate(state, args.section, args.need)
+    emit({"gate": "blocked" if blocked else "pass", "results": results}, 1 if blocked else 0)
+
+
+if __name__ == "__main__":
+    main()