wizz-method 2.21.0 → 2.22.0

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

package/src/skills-lib/wizz-premium-landing-ui-researcher/SKILL.md

@@ -11,7 +11,7 @@ Autonomous strategist for premium landing pages, SaaS UI, and advanced visual ex
 
 Check for `{output_folder}/design-state.yaml` (default `_wizz-output/`). Cheap check first: `grep -c 'status: open'`. Not there? Run `find . -name design-state.yaml -not -path '*/node_modules/*'` before concluding it does not exist: a map found elsewhere is still the map, so use it and tell the user it is off-place.
 
-- **It exists, with open needs:** you are not deciding what to research. Work **one need per pass**, in the order given, and take `query`, `budget.fontes` and `floor` as given. Read the `proibidos` block before writing any query: a query that lands on a forbidden capability is not run, not even for comparison. Write each finding back under `discoveries` with the `need` id, and move the need to `selected` or `unmet` with a reason. Stop when the needs are exhausted, not when the ideas are.
+- **It exists, with open needs:** you are not deciding what to research. Work **one need per pass**, in the order given, and take `query`, `budget.fontes` and `floor` as given. Read the `proibidos` block before writing any query: a query that lands on a forbidden capability is not run, not even for comparison. Judge each candidate with [mining-rubric](references/mining-rubric.md) (entry conditions, score, verdict, selection) and write it back under `discoveries` with the `need` id. Each need closes on one of the rubric's stop conditions, never on a feeling of having seen enough. After writing, run `uv run --no-cache ../wizz-design-needs/scripts/design_state.py validate {output_folder}/design-state.yaml` and fix its findings before the handoff. Stop when the needs are exhausted, not when the ideas are.
 - **It exists, no open needs:** the map is done. Do not open new research on your own: report it and hand back to `wizz-design-needs` if something is genuinely missing.
 - **It does not exist, and the work is non-trivial:** invoke `skill:wizz-design-needs` first. Mining without a map is how a project ends up depending on the user to name every effect, one request at a time.
 - **It does not exist, and the work is one isolated component the user named:** proceed, and say the map was not created.
@@ -28,6 +28,8 @@ Absolute rule: inspect real sources, log evidence, and recommend options, adapt
 
 ## Gate 2: classify the site's level (always, before recommending components)
 
+The brief and the visual identity belong to `wizz-decision-maker` (`brief` and `identidade` in `design-state.yaml`): when they exist, read objective, audience and references from them instead of asking again, and never redefine palette or typography here. This skill owns only the level classification and the component and motion research.
+
 If essential data is missing, ask at most 5 strategic questions: (1) business/product/offer, (2) target audience, (3) page's main objective, (4) desired visual level, (5) existing visual references. If the user doesn't answer everything, continue with coherent strategic hypotheses. Master rule: ask, infer, execute.
 
 Classify the project into one of 5 levels (rules, allowed/forbidden motion, and budget per level in [site-levels](references/site-levels.md)):
@@ -60,7 +62,8 @@ Classify the project into one of 5 levels (rules, allowed/forbidden motion, and
 | Handoffs to wizz-motion-3d-director and wizz-implementation-planner, final ladder rule | [handoffs](references/handoffs.md) |
 | SaaS Dashboard Mode and Portfolio / Authority Site Mode | [dashboard-and-portfolio-modes](references/dashboard-and-portfolio-modes.md) |
 | The mandatory 12-step process and honesty checkpoint | [mandatory-process](references/mandatory-process.md) |
-| The 5-phase protocol (inventory, public search, cache, evidence, adaptation) | [source-first-protocol](references/source-first-protocol.md) |
+| The 6-phase protocol (inventory, public search, cache, evidence, adaptation, stop) | [source-first-protocol](references/source-first-protocol.md) |
+| Entry conditions, 0-10 score, verdicts, selection, stop conditions, dedup and the adaptation protocol | [mining-rubric](references/mining-rubric.md) |
 | Audit Protocol: Pass 1 Taste, Pass 2 Impeccable, Pass 3 Cross-check, Pass 4 A11y/Perf | [audit-protocol](references/audit-protocol.md) |
 | Component sources (React Bits, Cult UI, Ali Imam, Watermelon, StyleUI, Skiper UI, Bklit UI, Componentry), animation engines (GSAP, anime.js), reference and visual inspiration sources, Clone Policy, Paid Source Policy | [component-sources](references/component-sources.md) |
 | Default stack, visual direction, palettes, typography, and animation selection rules | [stack-and-visual-direction](references/stack-and-visual-direction.md) |
@@ -68,6 +71,7 @@ Classify the project into one of 5 levels (rules, allowed/forbidden motion, and
 | Base prompts (complete landing page and 3D scroll hero) | [prompt-templates](references/prompt-templates.md) |
 | Final response format, Quality Bar, and self-check before closing the delivery | [output-format-and-quality](references/output-format-and-quality.md) |
 | Direct links to every authorized source | [source-links](references/source-links.md) |
+| The source catalogue as data (kind, access, license, need tags, cache folder), queried with `scripts/design_sources.py list --need <tag>`; cache freshness and refresh with `freshness` / `refresh` | [design-sources.yaml](references/design-sources.yaml) |
 | Opening web access before mining, BLOCKED, and the evidence gate before delivering | [web-access-and-evidence](references/web-access-and-evidence.md) |
 
 Final rule: never put real keys inside the skill (environment variables only), and never deliver a landing page that looks like a template with no positioning.

package/src/skills-lib/wizz-premium-landing-ui-researcher/references/audit-protocol.md

@@ -4,51 +4,24 @@ The Source-First Protocol takes care of the **beginning** (curating mature sourc
 
 Apply 3 passes in order. Each catches a different class of problem: using the first two is redundant only 60% of the time; in the other 40%, one catches what the other missed.
 
-### Pass 1: Taste Skill (early, before full implementation)
+### Pass 1: Taste (early, before full implementation)
 
 **When to apply:** right after Phase 5 of the Source-First Protocol, when you have a mockup/wireframe of the sections or a first version of the hero implemented. Ideally there's still time to swap a component without high cost.
 
-**Source:** `https://github.com/Leonxlnx/taste-skill.git`
+**Run:** invoke `skill:wizz-taste-skill` in audit mode. Its checklist is the list for this pass: [design-audit](../../wizz-taste-skill/references/design-audit.md) and [anti-slop-tells](../../wizz-taste-skill/references/anti-slop-tells.md), including the landing-page tells of section 9.H. This protocol keeps only when to run it, the angle and the output, so the list has one owner and cannot drift.
 
 **Angle:** an anti-AI-generic detector. Key question: *"Could this layout belong to any generic SaaS, or does it have an authorial signature?"*
 
-**What to look for and flag as a problem:**
-
-- A hero with "big headline + subtitle + 2 side-by-side CTAs" with no identity of its own
-- Features in a 3-col grid with cute decorative icons (the "✨ Fast 🚀 Reliable 🔥 Secure" style)
-- Saturated color gradients with no purpose (purple-to-pink, blue-to-cyan, the default Tailwind look)
-- AI copy: "revolutionize your workflow", "supercharge your business", "10x your results"
-- A perfectly symmetrical layout with no editorial tension
-- Excessive rounded corners (`rounded-3xl` on everything)
-- Card stacks with the default Tailwind `shadow-xl`
-- Decorative emoji anywhere other than status microcopy
-- Generic testimonial cards with a round avatar + name + title + quoted sentence
-- Pricing cards with a centered, gradient "Most Popular" badge
-
-**Pass output:** a list of up to 5 spots where the landing page looks templated, with a **replacement** suggestion for each one (a component from an authorized source, an editorial decision, or removal). Present it to the user before proceeding.
+**Pass output:** a list of up to 5 spots where the landing page looks templated, with a **replacement** suggestion for each one (a component from an authorized source, an editorial decision, or removal). Present it to the user before proceeding. A replacement that needs a new component reopens the need in `design-state.yaml` instead of starting a fresh search.
 
 ### Pass 2: Impeccable (late, with real tokens and content)
 
 **When to apply:** after the implementation is assembled with brand tokens, real typography, real images/mockups. Catches problems that only appear once the component is alive, not in a wireframe.
 
-**Source:** `https://github.com/pbakaus/impeccable.git`
+**Run:** invoke `skill:wizz-impeccable` with `critique` (or `polish` when fixing). Its ruleset is the list for this pass: [design-rules](../../wizz-impeccable/references/design-rules.md), including the "Landing fine-tuning" block. Same split as Pass 1: the list lives in the skill, the timing and output live here.
 
 **Angle:** classic design chops. Key question: *"Does this look like it was made by a senior designer with 10+ years of editorial background?"*
 
-**What to look for and flag as a problem:**
-
-- **Spacing**: inconsistent padding/margin between sections (24px here, 28px there, 32px elsewhere). Define and follow a scale (4/8/12/16/24/32/48/64/96/128)
-- **Hierarchy**: headings competing with each other for weight/size. H1, H2, H3 should have clear contrast
-- **Leading**: `line-height` too tight in body text (<1.5) or too loose in headlines (>1.15)
-- **Tracking**: wrong letter-spacing on small uppercase text (mono labels need more tracking, ~0.18em)
-- **Optical alignment**: icons with a different visual weight than adjacent text, mono numbers not monospaced vertically
-- **Vertical rhythm**: scrolling with no breathing room (section after section with no air) or with unexplainable huge gaps
-- **Color hierarchy**: 5+ shades of gray for text with no justification, accent color used on things that aren't actionable
-- **Image cropping**: thumbnails with inconsistent aspect ratio between cards
-- **Typographic contrast**: heavy headings + heavy body text too (missing a light/regular weight to create contrast)
-- **Edge cases**: what happens when the project name has 4 words vs. 1? And when the description has 2 lines vs. 4?
-- **Focus states**: does the tab order deliver an editorial sequence, or does it jump around chaotically between sections?
-
 **Pass output:** a list of up to 7 fine-tuning adjustments with specific **before/after** (e.g., "Hero subhead: change leading 1.1 → 1.3" / "Cards grid: align the mono numbering baseline with the card headline baseline").
 
 ### Pass 3: Cross-check with references
@@ -82,7 +55,7 @@ agent-browser eval "<js>"       # 4. measure tokens (computed styles, etc.)
 **Diagnosis:**
 
 - If the difference is **taste/direction** (conscious brand choices) → ok, keep it
-- If the difference is **execution** (the reference has polish yours is missing) → go back to Source-First and find the missing component
+- If the difference is **execution** (the reference has polish yours is missing) → reopen the need in `design-state.yaml` (status `open`, with the discoveries already rejected carried forward) and mine it again; with no state file, go back to Source-First and find the missing component
 - If the difference is **motion fluidity** → review timing, easing, scale, and animation composition (the Design Motion Principles were probably not applied)
 - If the difference is **visual density** (the reference is more spaced out and breathes more) → cut elements, don't add
 
@@ -106,8 +79,8 @@ Not a matter of taste, it's technical quality. Check:
 
 | Pass | When | Adjustment cost | Frequency |
 |---|---|---|---|
-| 1. Taste Skill | Wireframe / hero first | Low (component can still be swapped) | Always |
-| 2. Impeccable | Implementation with real tokens | Medium (fine CSS) | Always |
+| 1. Taste (`wizz-taste-skill`) | Wireframe / hero first | Low (component can still be swapped) | Always |
+| 2. Impeccable (`wizz-impeccable`) | Implementation with real tokens | Medium (fine CSS) | Always |
 | 3. Cross-check | Final visual | Variable | Always |
 | 4. Accessibility + Perf | Before delivering | Medium-high (may require refactor) | Always |
 

package/src/skills-lib/wizz-premium-landing-ui-researcher/references/component-sources.md

@@ -1,3 +1,5 @@
+> To pick a source, query [design-sources.yaml](design-sources.yaml) with `scripts/design_sources.py list --need <tag>`; this page is the policy and nuance behind those rows, read when a source needs it.
+
 ## Source Access Strategy
 
 Prioritize free, open source, public, registry-based sources or sources provided by the user.