wizz-method 2.20.1 → 2.22.0

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()

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

@@ -0,0 +1,143 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["pytest>=8.0", "ruamel.yaml>=0.18"]
+# ///
+"""Tests for design_state.py: rubric validation and the implementation gate."""
+
+import copy
+import importlib.util
+import json
+
+import pytest
+from pathlib import Path
+
+SCRIPT = Path(__file__).resolve().parents[1] / "design_state.py"
+spec = importlib.util.spec_from_file_location("design_state", SCRIPT)
+mod = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(mod)
+
+RUBRIC = mod.load_rubric()
+CEILING = mod.load_ceiling()
+
+ADAPTATION = {
+    "padrao": "o título é revelado por uma máscara que sobe com o scroll",
+    "por_que": "segura o olho no título",
+    "invariante": "a máscara anda mais rápido que o scroll",
+    "variavel": ["easing", "duração"],
+    "reimplementacao": "tokens do projeto",
+}
+
+BASE = {
+    "version": 1,
+    "nivel": 1,
+    "needs": [
+        {"id": "b1", "surface": "home", "section": "hero", "layer": "comportamento", "why": "brief editorial", "floor": 7,
+         "status": "selected", "satisfied_by": ["d1"]},
+        {"id": "s1", "surface": "home", "section": "projetos", "layer": "secao", "why": "portfólio", "floor": 6,
+         "status": "open"},
+        {"id": "s2", "surface": "home", "section": "contato", "layer": "secao", "why": "captar contato",
+         "status": "unmet", "reason": "2 fontes secas"},
+    ],
+    "discoveries": [
+        {"id": "d1", "need": "b1", "surface": "home", "layer": "comportamento", "evidence": "verified",
+         "pattern_key": "scroll-mask-reveal", "observed": ["420ms"], "disqualifiers": [],
+         "scores": {"aderencia": 3, "execucao": 2, "custo_adaptacao": 2, "custo_performance": 1, "originalidade": 1, "total": 9},
+         "verdict": "ASSINATURA", "adaptation": ADAPTATION, "status": "selected"},
+        {"id": "d2", "need": "b1", "surface": "home", "layer": "comportamento", "evidence": "verified",
+         "pattern_key": "fade-up", "observed": ["fade"], "disqualifiers": ["reduced_motion"],
+         "verdict": "DESCARTAR", "status": "rejected", "reason": "ignora reduced motion"},
+    ],
+}
+
+
+def state(**changes):
+    data = copy.deepcopy(BASE)
+    for key, value in changes.items():
+        data[key] = value
+    return data
+
+
+def codes(data):
+    return {item["code"] for item in mod.validate(data, RUBRIC, CEILING)}
+
+
+def test_rubric_and_ceiling_are_read_from_the_skill_files():
+    assert RUBRIC["cut"] == 6 and "licenca" in RUBRIC["disqualifiers"]
+    assert CEILING[1] == 1 and CEILING[5] == 8
+
+
+def test_consistent_state_has_no_findings():
+    assert mod.validate(state(), RUBRIC, CEILING) == []
+
+
+def test_verdict_must_match_the_band():
+    data = state()
+    data["discoveries"][0]["verdict"] = "FORTE"
+    assert "verdict_band" in codes(data)
+    data["discoveries"][0]["reason"] = RUBRIC["signature_cap_reason"]
+    assert "verdict_band" not in codes(data)
+
+
+def test_entry_condition_forces_descartar_and_blocks_selection():
+    data = state()
+    data["discoveries"][1]["verdict"] = "UTILITARIO"
+    data["discoveries"][1]["status"] = "selected"
+    found = codes(data)
+    assert {"verdict_band", "selected_discarded"} <= found
+
+
+def test_selected_below_the_need_floor_and_without_adaptation():
+    data = state()
+    disc = data["discoveries"][0]
+    disc["scores"] = {"aderencia": 2, "execucao": 1, "custo_adaptacao": 2, "custo_performance": 1, "originalidade": 0}
+    disc["verdict"] = "UTILITARIO"
+    disc["adaptation"] = {"padrao": "x"}
+    assert {"selected_below_floor", "adaptation_missing"} <= codes(data)
+
+
+def test_two_signatures_on_one_surface_and_behaviour_ceiling():
+    data = state()
+    second = copy.deepcopy(data["discoveries"][0])
+    second.update(id="d3", pattern_key="cursor")
+    data["discoveries"].append(second)
+    assert {"signature_cap", "behaviour_ceiling"} <= codes(data)
+
+
+def test_reasons_and_dedup_links():
+    data = state()
+    data["needs"][2]["reason"] = None
+    data["discoveries"][1]["reason"] = None
+    data["discoveries"].append({"id": "d4", "need": "b1", "evidence": "verified", "observed": ["x"],
+                                "pattern_key": "other", "dup_of": "d1", "status": "rejected", "reason": "dup"})
+    assert {"need_reason", "discovery_reason", "dup_of"} <= codes(data)
+
+
+def test_gate_passes_selected_and_blocks_open_and_unplanned():
+    blocked, results = mod.gate(state(), ["home/hero"], [])
+    assert not blocked and results[0]["discoveries"] == ["d1"]
+    blocked, results = mod.gate(state(), ["home/projetos"], [])
+    assert blocked and results[0]["result"] == "blocked"
+    blocked, results = mod.gate(state(), ["home/rodape"], [])
+    assert blocked and results[0]["result"] == "unplanned"
+
+
+def test_gate_lets_unmet_through_with_the_justification():
+    blocked, results = mod.gate(state(), [], ["s2"])
+    assert not blocked and "from scratch" in results[0]["action"]
+
+
+def test_cli_exit_codes(tmp_path, capsys):
+    from ruamel.yaml import YAML
+
+    path = tmp_path / "design-state.yaml"
+    with open(path, "w", encoding="utf-8") as handle:
+        YAML().dump(state(), handle)
+    with pytest.raises(SystemExit) as ok:
+        mod.main(["validate", str(path)])
+    assert ok.value.code == 0 and json.loads(capsys.readouterr().out)["ok"] is True
+    with pytest.raises(SystemExit) as blocked:
+        mod.main(["gate", str(path), "--section", "home/projetos"])
+    assert blocked.value.code == 1 and json.loads(capsys.readouterr().out)["gate"] == "blocked"
+    with pytest.raises(SystemExit) as missing:
+        mod.main(["validate", str(tmp_path / "nope.yaml")])
+    assert missing.value.code == 2

package/src/skills-lib/wizz-impeccable/references/design-rules.md

@@ -48,6 +48,24 @@ One hard typographic ceiling you currently miss:
 **Gemini-specific defect: hard ban.** Never animate `<img>` elements on hover. This includes any `transform` on `:hover` of an image, AND `.group:hover .group-hover\:scale` / `.group:hover .group-hover\:rotate` / `.group:hover .group-hover\:translate` patterns from Tailwind that animate a child image via a parent hover. This is your single most common motion tell; it adds no information (the image isn't an action target) and reads as "AI animated this because it could". If a card needs hover feedback, animate the card's background, border, or shadow. Never the image, never via the image's parent. <!-- rule:skill-interaction-gemini-no-image-hover -->
 </gemini>
 
+#### Landing fine-tuning (Wizz addition, moved here from the landing Audit Protocol)
+
+Run with real tokens, real typography and real images; these only show once the page is alive.
+
+- **Spacing scale.** Section padding and margins follow one scale (4/8/12/16/24/32/48/64/96/128), not 24 here and 28 there.
+- **Heading hierarchy.** H1, H2 and H3 do not compete: each step has clear size or weight contrast.
+- **Leading.** Body `line-height` ≥ 1.5; display headlines ≤ 1.15.
+- **Small uppercase tracking.** Mono and small-caps labels need more tracking (~0.18em).
+- **Optical alignment.** Icons match the visual weight of adjacent text; mono numbers line up on a shared baseline.
+- **Vertical rhythm.** No run of sections without air, no unexplained huge gap.
+- **Colour hierarchy.** Five or more greys for text need a reason; the accent goes only on what is actionable.
+- **Image cropping.** Thumbnails in one grid share an aspect ratio.
+- **Weight contrast.** Heavy headings need a light or regular body to read against.
+- **Content edge cases.** Check a 1-word and a 4-word project name, a 2-line and a 4-line description.
+- **Tab order.** Focus follows the editorial sequence of the page, not a jump between sections.
+
+Output of this check: up to 7 adjustments, each as a specific before/after (e.g. "Hero subhead: leading 1.1 → 1.3").
+
 ### New projects only (when no prior work exists)
 
 #### Color & Theme

package/src/skills-lib/wizz-motion-3d-director/references/motion-paths.md

@@ -29,6 +29,8 @@ Use when you need **real interaction**.
 - Framer Motion or Motion for scroll integration;
 - GSAP (ScrollTrigger) when scroll orchestrates the scene — 100% free since v3.13, all plugins included.
 
+**Reference for fluid effects:** when the brief asks for a fluid cursor trail, liquid distortion or ink-like smoke over a Three.js scene, `artcodev/three-fluid-fx` (MIT, npm `three-fluid-fx`, 0.1.0 on 2026-10-24) is a drop-in 2D Stable-Fluids solver with WebGL/GLSL and WebGPU/TSL pipelines. Pointer only: the method does not install it, and an early version means pinning the exact release and checking the mobile cost against the performance targets before adopting it.
+
 **Examples:** a 3D object that follows the cursor; a mouse-reactive particle sphere; a camera that advances on scroll; real-time wireframe terrain; a configurable 3D product; an interactive WebGL background.
 
 **Avoid if:**

package/src/skills-lib/wizz-paid-ads/SKILL.md

@@ -86,7 +86,8 @@ LI_LeadGen_CMOs-SaaS_Whitepaper_Mar24
 
 **Scaling phase:**
 - Consolidate budget into winning combinations
-- Increase budgets 20-30% at a time
+- On Meta with a bid cap campaign, follow the order in `wizz-lowticket-metodologia` `knowledge/03-campanha-bidcap.md`: bid cap first, then validated creatives, then budget by the ROAS ruler
+- Without a bid cap (other platforms, or a campaign not built on it yet): increase budgets 20-30% at a time
 - Wait 3-5 days between increases for algorithm learning
 
 ---