wizz-method 2.20.1 → 2.22.0

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.

package/src/skills-lib/wizz-premium-landing-ui-researcher/references/design-sources.yaml

@@ -0,0 +1,252 @@
+# Design sources, as data. Read by scripts/design_sources.py (list by need tag,
+# cache freshness, refresh) so the miner does not load the whole prose catalogue
+# to pick one source. The prose in component-sources.md stays as the reference
+# for policy and nuance (Clone Policy, Paid Source Policy, visual inspiration
+# rules); this file is the one to query.
+#
+# Fields:
+#   kind     code | registry | engine | visual | taste | extractor
+#            (code/registry = evidence bar of code; visual = pattern only, rebuilt)
+#   license  what was read, with the date of the reading in `checked`; null = none
+#   access   free | free+paid | paid | login
+#   need_tags  what the source answers; matched by `design_sources.py list --need`
+#   registry   shadcn namespace and item URL template, when it has one
+#   cache      folder name under ~/.claude/design-sources/, when there is a local clone
+#   study_only true when the code must never be copied (no license)
+version: 1
+cache_root: "~/.claude/design-sources"
+max_cache_age_days: 30
+registry_index: "https://ui.shadcn.com/r/registries.json"
+
+sources:
+  - id: react-bits
+    kind: registry
+    url: "https://github.com/DavidHDev/react-bits.git"
+    registry: { namespace: "@react-bits" }
+    license: "MIT + Commons Clause"
+    checked: 2026-09-06
+    access: free+paid
+    cache: react-bits
+    need_tags: [text-animation, background, scroll, hover, card, micro-interaction, loader, hero, particles, cursor]
+    note: "React Bits Pro is never a mandatory dependency."
+
+  - id: cult-ui
+    kind: registry
+    url: "https://github.com/nolly-studio/cult-ui"
+    docs: "https://www.cult-ui.com/docs"
+    registry: { namespace: "@cult-ui" }
+    license: null
+    checked: null
+    access: free+paid
+    cache: cult-ui
+    need_tags: [marketing-section, hero, button, card, landing-section]
+    note: "Read the license of the item; public/open resources only unless paid access is confirmed."
+
+  - id: ali-imam
+    kind: visual
+    url: "https://github.com/aliimam-in/aliimam.git"
+    license: null
+    checked: 2026-10-15
+    access: free
+    cache: aliimam
+    study_only: true
+    need_tags: [shader, liquid, ripple, border-glow, bento, typewriter, canvas, experimental]
+    note: "No license: study the technique, never copy the code."
+
+  - id: watermelon
+    kind: registry
+    url: "https://github.com/WatermelonCorp/watermellon-registry.git"
+    registry: { namespace: "@watermelon", template: "https://registry.watermelon.sh/r/{name}.json" }
+    license: null
+    checked: null
+    access: free
+    cache: watermelon
+    need_tags: [dashboard, saas, card, app-section, data-viz, product-ui]
+
+  - id: styleui
+    kind: registry
+    url: "https://github.com/heyfabrika/styleui.git"
+    registry: { namespace: "@styleui" }
+    license: null
+    checked: 2026-10-15
+    access: free
+    cache: styleui
+    need_tags: [layout, template, landing-section, base-page]
+    note: "Marked degraded in the shadcn index on 2026-10-15: check health before relying on it."
+
+  - id: componentry
+    kind: registry
+    url: "https://componentry.dev/"
+    registry: { namespace: "@componentry", template: "https://componentry.fun/r/{name}.json" }
+    license: null
+    checked: null
+    access: free
+    need_tags: [text-animation, background, hover, micro-interaction, animated-component]
+
+  - id: bklit-ui
+    kind: registry
+    url: "https://github.com/bklit/bklit-ui"
+    registry: { namespace: "@bklit" }
+    license: MIT
+    checked: null
+    access: free
+    need_tags: [chart, data-viz, dashboard, metrics]
+    note: "Install from the registry, do not clone."
+
+  - id: skiper-ui
+    kind: registry
+    url: null
+    registry: { namespace: "@skiper-ui" }
+    license: null
+    checked: null
+    access: free+paid
+    need_tags: [distinctive-effect, premium-section, advanced-animation]
+    note: "Must not be cloned: npx shadcn add @skiper-ui/<item>. Premium only with confirmed access."
+
+  - id: shadcn-ui
+    kind: registry
+    url: "https://ui.shadcn.com/"
+    license: MIT
+    checked: null
+    access: free
+    need_tags: [base, form, dialog, navigation, carousel, layout]
+
+  - id: embla
+    kind: code
+    url: "https://www.embla-carousel.com/"
+    license: MIT
+    checked: null
+    access: free
+    need_tags: [carousel]
+
+  - id: animmaster
+    kind: code
+    url: "https://animmasterlib.dev/"
+    license: "commercial"
+    checked: null
+    access: paid
+    need_tags: [animated-component]
+    note: "Only with authorized access; what the user already bought counts as local material."
+
+  - id: gsap
+    kind: engine
+    url: "https://github.com/greensock/GSAP.git"
+    license: "free since v3.13, all plugins"
+    checked: null
+    access: free
+    need_tags: [scroll-storytelling, scroll, timeline, text-reveal, svg-morph]
+
+  - id: animejs
+    kind: engine
+    url: "https://github.com/juliangarnier/anime.git"
+    license: MIT
+    checked: null
+    access: free
+    need_tags: [micro-interaction, stagger, svg, counter]
+
+  - id: design-motion-principles
+    kind: taste
+    url: "https://github.com/kylezantos/design-motion-principles.git"
+    license: null
+    checked: null
+    access: free
+    need_tags: [motion-principles, easing, timing]
+
+  - id: vibe-code-components
+    kind: visual
+    url: "https://vibecodecomponents.com/"
+    license: null
+    checked: null
+    access: free
+    need_tags: [visual-direction, section-idea]
+
+  - id: landing-love
+    kind: visual
+    url: "https://www.landing.love/"
+    license: null
+    checked: null
+    access: free
+    need_tags: [visual-direction, scroll, hero, landing-section]
+
+  - id: recent
+    kind: visual
+    url: "https://recent.design/"
+    license: null
+    checked: 2026-10-15
+    access: free
+    need_tags: [visual-direction, typography, editorial, art-direction]
+
+  - id: design-spells
+    kind: visual
+    url: "https://www.designspells.com/"
+    license: null
+    checked: null
+    access: free
+    need_tags: [micro-interaction, delight, hover]
+
+  - id: spline
+    kind: visual
+    url: "https://spline.design/"
+    license: null
+    checked: null
+    access: free+paid
+    need_tags: [3d, hero]
+
+  - id: unicorn-studio
+    kind: visual
+    url: "https://www.unicorn.studio/"
+    license: null
+    checked: null
+    access: free+paid
+    need_tags: [webgl, background, shader, particles]
+
+  - id: refero
+    kind: visual
+    url: "https://refero.design/"
+    license: null
+    checked: 2026-10-15
+    access: login
+    need_tags: [ux-flow, dashboard, pricing, onboarding]
+    note: "Refero MCP is paid."
+
+  - id: refero-styles
+    kind: taste
+    url: "https://styles.refero.design/"
+    license: null
+    checked: null
+    access: free
+    need_tags: [design-md, typography, palette, spacing]
+
+  - id: awesome-design-md
+    kind: taste
+    url: "https://github.com/VoltAgent/awesome-design-md"
+    license: MIT
+    checked: 2026-10-15
+    access: free
+    need_tags: [design-md, typography, palette, spacing]
+
+  - id: mobbin
+    kind: visual
+    url: "https://mobbin.com/"
+    license: null
+    checked: 2026-10-15
+    access: login
+    need_tags: [ux-flow, onboarding, pricing, dashboard, mobile]
+    note: "Mobbin MCP is paid."
+
+  - id: screensdesign
+    kind: visual
+    url: "https://screensdesign.com/"
+    license: null
+    checked: 2026-10-15
+    access: login
+    need_tags: [mobile, onboarding, paywall, subscription]
+
+  - id: dembrandt
+    kind: extractor
+    url: "https://github.com/dembrandt/dembrandt"
+    license: MIT
+    checked: 2026-10-15
+    access: free
+    need_tags: [typography, palette, spacing, design-md]
+    note: "npx -y dembrandt@0.39.2 <url> --design-md: measures a site the user named."

package/src/skills-lib/wizz-premium-landing-ui-researcher/references/mandatory-process.md

@@ -8,7 +8,7 @@ Always follow this process. **Steps 6, 7, and 8 are SOURCE CHECKPOINTS and must
 4. Define the visual direction.
 5. Decide whether it needs a landing page, dashboard, 3D/WebGL, or a combination.
 6. **CHECKPOINT: Inventory of the user's sources.** List and inspect (ls + minimal reading of READMEs/package.json) the current project and the models at the paths provided by the user; reuse the memory summary from the handoff. Identify which components/effects the user already has that can be reused before any external source.
-7. **CHECKPOINT: Source-First Protocol (mandatory).** Run [source-first-protocol](source-first-protocol.md): search public sources, open demos and code/registry, check revision, license, and dependencies. Log evidence and failures in the research artifact; show 1-3 real candidates per component.
+7. **CHECKPOINT: Source-First Protocol (mandatory).** Run [source-first-protocol](source-first-protocol.md): search public sources, open demos and code/registry, check revision, license, and dependencies. Log evidence and failures in the research artifact; judge each verified candidate with [mining-rubric](mining-rubric.md) and show the selected one per need, with at most two runners-up and their verdicts.
 8. **CHECKPOINT: Choose sources.** Recommend the appropriate combination. With direction and implementation already authorized, proceed; only ask if a material decision is missing.
 9. Recommend components and animations (already curated in the previous checkpoints).
 10. Write copy and structure.

package/src/skills-lib/wizz-premium-landing-ui-researcher/references/mining-rubric.md

@@ -0,0 +1,123 @@
+# Mining rubric: entry conditions, score, verdict, stop and adaptation
+
+Shared by `wizz-premium-landing-ui-researcher` and `wizz-ui-component-curator`. Read it before judging the first candidate of a need. It turns "this looks good" into a verdict that the next session, the implementer and QA can read back from `design-state.yaml`.
+
+The discipline is ported from the offer miner (`wizz-lowticket-minerador`): conditions checked before any score, a 0-10 score with a cut at 6, an enumerated verdict, a stop rule per need, observation kept apart from inference, and a fixed read order that rebuilds instead of copying.
+
+Order of work for each candidate, always the same:
+
+1. **Evidence gate** ([web-access-and-evidence](web-access-and-evidence.md)). Missing any of the five fields = `evidence: unverified`. Unverified is not scored and never selected; it can be verified later.
+2. **Dedup.** Its `pattern_key` is already `selected` in the project → `status: rejected`, `dup_of: <that discovery>`. Not scored.
+3. **Entry conditions.** One unmet = `verdict: DESCARTAR` with the code in `disqualifiers`. Not scored.
+4. **Score** the five criteria, sum, read the verdict from the band.
+5. **Select or keep searching**, by the selection and stop rules below.
+6. **Adapt** the selected one with the five-step protocol.
+
+## Entry conditions
+
+Each one is a condition of use, not a ban: the line says what makes the candidate eligible. A candidate that does not meet a condition is recorded with the code and the reason, so the next round does not open it again.
+
+| Code | The candidate is eligible when | Unmet means |
+|---|---|---|
+| `licenca` | a code source (`kind: code` or `registry`) has a license that allows use in this project | no license or an incompatible one. Reclassify it as `kind: visual` and it is scored as a pattern to rebuild, never as code to copy |
+| `acesso_pago` | paid access is already authorized by the user | access or cost not confirmed (the user decides, it is a faixa C item) |
+| `dependencia` | its dependencies fit the stack and the bundle budget of `design-state.stack` | it pulls a dependency outside the stack or above the budget, and the user has not approved going over |
+| `reduced_motion` | it honours `prefers-reduced-motion`, or the adaptation plan writes that path | it ignores reduced motion and nobody wrote the alternative |
+| `contraste` | its contrast passes AA once the project's tokens are applied | the effect itself breaks AA (text over moving image with no scrim, glow under body text) |
+| `nivel` | the motion is allowed at the site level ([site-levels](site-levels.md)) | the level lists that motion as one to avoid |
+| `proibido` | it does not land on a capability in the `proibidos` block | it does. A reference the user chose already moved its item out of `proibidos` (derivation rule 4.4 of `wizz-design-needs`), so it is eligible |
+
+## Score
+
+Five criteria, summed to 0-10. Score only what was observed in this session; a criterion that rests on an inference is scored from what was seen and the inference is written in `inferred`.
+
+| Criterion | Range | Top of the range | Bottom of the range |
+|---|---|---|---|
+| `aderencia` | 0-3 | answers the need's `question` and fits the style DNA and brief signals as is | adjacent to the need, does not answer it |
+| `execucao` | 0-2 | polished in the live demo: timing, states, resize, mobile | broken or janky. Inspected static only: at most 1 |
+| `custo_adaptacao` | 0-2, inverted | token-level adaptation (colour, type, spacing) | most of it has to be rewritten |
+| `custo_performance` | 0-2, inverted | no new dependency, no layout thrash | heavy runtime (WebGL, video, large library) for what it adds |
+| `originalidade` | 0-1 | not the default look of the stack or the catalogue | reads as template |
+
+Middle values: `aderencia` 2 = answers the question with visible restyling, 1 = answers part of it; `execucao` 1 = works with rough edges; `custo_adaptacao` 1 = markup or API changes; `custo_performance` 1 = a new dependency inside the budget, or a measurable runtime cost.
+
+## Verdict
+
+| Verdict | Score | Use |
+|---|---|---|
+| `ASSINATURA` | 9-10 | the piece that defines the surface. At most one selected per surface |
+| `FORTE` | 7-8 | enters |
+| `UTILITARIO` | 6 | enters only when the need has nothing better |
+| `DESCARTAR` | 0-5, or an unmet entry condition | does not enter; the reason stays recorded |
+
+The cut is 6. A need's `floor` can raise it for that need, never lower it: a 7 on a need with `floor: 8` stays `FORTE` and is not selected for that need.
+
+The signature cap is what stops a page from becoming a collage of impressive effects. When a second candidate on the same surface scores 9 or 10, it is recorded as `FORTE` with `reason: "teto de assinatura"`.
+
+## Selection
+
+Per need, one discovery is selected: the highest-scoring verified, eligible candidate at or above the need's floor.
+
+- **Faixa A, silent:** the first leads the second by 2 points or more and the need is not `signature: true`. Select and move on.
+- **Faixa B, announced:** a tie within 1 point, or the signature piece of a surface. Select, then say which one won, the runner-up and why. The swap costs one edit to the state file.
+- `UTILITARIO` is selected only when no `FORTE` or `ASSINATURA` is eligible for that need.
+- Everything else on the need stays `proposed` or goes to `rejected` with a `reason`.
+
+## Stop conditions
+
+The miner stops on the first one that applies. Each stop writes the need's status and reason to the state file.
+
+| Scope | Stops when | Need status |
+|---|---|---|
+| Need, early | an eligible candidate scores 9 or more | `selected` |
+| Need, budget | the sources opened reach `budget.fontes` | `selected` if anything eligible, else `unmet` |
+| Need, diminishing returns | 2 sources in a row with nothing eligible at or above the floor | `unmet`, with what was tried. A result, not a failure |
+| Dedup | the need's question is already answered by a selected discovery on another surface | `dropped`, `reason: "resolvido por <need-id>"` |
+| Surface | the selected behaviour discoveries reach the level's behaviour ceiling (derivation rule 3 of `wizz-design-needs`) | the rest `deferred` |
+| Global | every need is `selected`, `unmet`, `dropped` or `deferred` | mining is over. This is "I have enough information" |
+
+Count the spend on the need itself (`spent.fontes`, `spent.secas`) so a reopened need starts from what was already paid.
+
+## Observation and inference
+
+Every discovery keeps two lists. `observed`: what was actually seen in this session (a duration in the code, an import, the demo jank at 375 px). `inferred`: the reading of it ("probably uses GSAP ScrollTrigger"). A score rests on `observed`. An inference written as an observation is the failure mode this split exists to catch.
+
+## Adaptation protocol
+
+Fixed read order, the design twin of the offer miner's "Demanda → Hook → Promessa…":
+
+**Pattern → Why it works → Invariant → Variable → Reimplementation**
+
+- **Pattern** (`padrao`): what happens mechanically, in one sentence, with no brand name.
+- **Why it works** (`por_que`): the perceptual or conversion reason. If it cannot be written, the discovery was not understood: it goes back to evaluation and is not selected.
+- **Invariant** (`invariante`): what cannot change without breaking the effect.
+- **Variable** (`variavel`): what is free (easing, duration, direction, colour, density).
+- **Reimplementation** (`reimplementacao`): the plan in the project's tokens and vocabulary.
+
+Closing rule, in the same spirit as the offer miner's: **a visual reference gives structure and principle, never CSS.** A code source with a license can be copied with attribution; a visual source is rebuilt.
+
+## Machine-readable block
+
+The eval (`evals/design-mining/`) and the state checker (`wizz-design-needs/scripts/design_state.py`) read the numbers from this block. Change a band here and both follow; nothing else holds a copy.
+
+```yaml
+# mining-rubric:v1
+cut: 6
+criteria:
+  aderencia: [0, 3]
+  execucao: [0, 2]
+  custo_adaptacao: [0, 2]
+  custo_performance: [0, 2]
+  originalidade: [0, 1]
+verdicts:
+  - { id: ASSINATURA, min: 9, max: 10 }
+  - { id: FORTE, min: 7, max: 8 }
+  - { id: UTILITARIO, min: 6, max: 6 }
+  - { id: DESCARTAR, min: 0, max: 5 }
+disqualifiers: [licenca, acesso_pago, dependencia, reduced_motion, contraste, nivel, proibido]
+signature_per_surface: 1
+signature_cap_reason: "teto de assinatura"
+faixa_a_lead: 2
+early_stop_score: 9
+dry_sources_to_unmet: 2
+```

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

@@ -12,7 +12,7 @@ Log the real paths of the resources found. If there are no local models, proceed
 
 ## Phase 2: Search and inspect public sources
 
-Choose sources based on the effect needed, using [component-sources](component-sources.md) and [source-links](source-links.md):
+Choose sources by querying the catalogue as data instead of reading the whole prose: `uv run --no-cache scripts/design_sources.py list --need <tag>` (run from this skill's folder; tags such as `hover`, `scroll`, `card`, `dashboard`, `chart`, `shader`, `typography`) returns the matching sources from [design-sources.yaml](design-sources.yaml) with kind, access, license and `study_only`. Without `uv`, read the YAML directly. [component-sources](component-sources.md) keeps the policy and nuance (clone, paid, visual inspiration) and [source-links](source-links.md) the links; open them when a source needs that detail. The quick map, for orientation:
 
 | Need | Initial sources |
 |---|---|
@@ -50,7 +50,7 @@ Most sources are shadcn registries. Read them live instead of cloning:
 2. **Read the item.** Replace `{name}` in the URL template and fetch the JSON: it carries the files, dependencies and registry dependencies, which is the evidence the gate asks for. When the shadcn MCP is configured (`npx shadcn@latest mcp init`), it does the same lookup for you.
 3. **Repos outside the index** (and offline work) use the local cache.
 
-An existing design cache (for example `~/.claude/design-sources/`) can be inspected. Don't treat it as up to date just because it exists:
+An existing design cache (for example `~/.claude/design-sources/`) can be inspected. Don't treat it as up to date just because it exists. One command answers it: `uv run --no-cache scripts/design_sources.py freshness` gives each cached clone's revision, last sync and `stale` past 30 days (`--remote` also compares with origin). A stale cache is still a source for a pattern, never for an API. `design_sources.py refresh` fast-forwards only the clones with no local changes and reports the rest; run it when the user agrees to update. The rules below still hold:
 
 - Check origin, branch, revision, and local changes before updating.
 - Check the remote revision when there's network access; the folder's modification date is not proof of being up to date.
@@ -70,10 +70,16 @@ Log in the existing design artifact (or create `design-research.md` in the proje
 
 Also include searches with no results and unavailable sources. Never fill in component names, paths, license, or test results by assumption. A row missing any of the five fields in [web-access-and-evidence](web-access-and-evidence.md) is UNVERIFIED and cannot be the recommendation.
 
-Show 1-3 compatible candidates per component, with a recommendation and adaptation cost. If the user has already authorized the implementation and defined the direction, choose the best option within that scope and proceed. Only ask when a material decision about direction, paid access, or scope change is missing.
+Judge every verified candidate with [mining-rubric](mining-rubric.md): dedup, entry conditions, the 0-10 score with the cut at 6, the verdict, and the selection rule. With a `design-state.yaml`, each candidate is written as a discovery with its need id, scores, verdict and status; the table above is the human-readable view of the same rows.
+
+Show the selected candidate per need and at most two runners-up, each with its verdict and score. If the user has already authorized the implementation and defined the direction, the selection rule decides and you proceed. Only ask when a material decision about direction, paid access, or scope change is missing.
 
 ## Phase 5: Adapt and verify
 
-Adapt tokens, typography, spacing, content, and motion to the project. Verify responsiveness, keyboard navigation, focus, contrast, reduced-motion, and rendering cost as appropriate for the component. Link the result back to the logged sources.
+Write the adaptation in the five-step order of [mining-rubric](mining-rubric.md) (pattern, why it works, invariant, variable, reimplementation) before touching code. Then adapt tokens, typography, spacing, content, and motion to the project. Verify responsiveness, keyboard navigation, focus, contrast, reduced-motion, and rendering cost as appropriate for the component. Link the result back to the logged sources.
 
 Building from scratch is acceptable for trivial primitives or when the documented research finds no compatible option and the implementation is authorized. Explain the reason. Don't claim something doesn't exist in any catalog; only report the sources actually researched.
+
+## Phase 6: Stop
+
+Mining stops by rule, not by patience. Per need: an eligible candidate at 9 or more, the source budget spent, or 2 sources in a row with nothing eligible (`unmet`, with what was tried). Per surface: the level's behaviour ceiling. Globally: every need in a terminal status. The table and the status each stop writes are in [mining-rubric](mining-rubric.md). Report which stop closed each need.

package/src/skills-lib/wizz-premium-landing-ui-researcher/references/web-access-and-evidence.md

@@ -36,6 +36,6 @@ Every candidate needs all five, collected in this session:
 | Dependencies | Read from the actual imports or registry JSON | Guessed from the component's name |
 | Source read | The code file was opened and its imports checked | The demo alone |
 
-A candidate missing any field is **UNVERIFIED**. UNVERIFIED items go in a separate section of the report, with what is missing and why. They are never recommended and never placed in the top 1-3, and the implementation plan never depends on them. If every candidate for a need is UNVERIFIED, the need is reported as `unmet`, not filled.
+A candidate missing any field is **UNVERIFIED**. UNVERIFIED items go in a separate section of the report, with what is missing and why. They are never recommended and never scored or selected by the [mining-rubric](mining-rubric.md), and the implementation plan never depends on them. If every candidate for a need is UNVERIFIED, the need is reported as `unmet`, not filled.
 
 Before closing, check the delivery against this gate once: every recommended item has its five fields in the research log (`design-research.md` or the project's design artifact), and the access line from Step 0 is in the report.