Fix .claude/skills data drift, harden search engine, tighten SKILL.md

[sunilchandarjr]

Summary

While auditing the plugin for reliability, I found that .claude/skills/ui-ux-pro-max/{data,scripts} -- the copy Claude Code actually loads when this repo is installed as a plugin -- had silently drifted from src/ui-ux-pro-max/ (the documented source of truth). cli/scripts/sync-assets.mjs and the "Check asset sync" workflow only ever covered cli/assets/; nothing checked the Claude Code skill copy. As a result:

• 6 of the 22 registered stacks (javafx, wpf, winui, avalonia, uno, uwp) had no CSV at all in that copy -- every search against them returned "Stack file not found".
• colors.csv, products.csv, styles.csv, typography.csv, and 4 stack CSVs (angular, astro, laravel, nuxt-ui) had stale, smaller content than src/ (e.g. colors.csv had 160 rows vs. 192 in src/).

Beyond fixing that drift, I also hardened the search engine and tightened SKILL.md while I was in there:

• Sync tooling: extended sync-assets.mjs (and CI trigger paths) to also sync/verify .claude/skills/ui-ux-pro-max/{data,scripts} against src/, so this can't silently drift again.
• core.py: tokenizer no longer loses short domain terms (ui, ux, 3d, gsap) without a proper stopword list; added a small synonym-normalization layer (e-commerce/ecommerce, a11y/accessibility, etc.); 0-result searches now return nearest-vocabulary suggestions instead of silent emptiness; CSV/BM25 indexes are cached by file mtime instead of rebuilt on every call inside a single --design-system run; domain auto-detection weights multi-word keyword matches and breaks ties deterministically (previously depended on dict ordering), and reports the runner-up domain.
• design_system.py: --persist no longer silently overwrites an existing MASTER.md -- it skips (with a clear message) unless --force is passed. generate_design_system() now returns a dict (text/design_system/persistence) instead of a bare string, enabling --json output for --design-system.
• search.py: field truncation is now per-column (code samples/checklists are never truncated); added --full, --force, and --json support for --design-system.
• Tests: added validate_data.py (stdlib-only) which checks that CSV_CONFIG/STACK_CONFIG columns actually exist in their CSV headers and that Decision_Rules JSON parses -- this complements (doesn't replace) the existing scripts/validate-csv.py, which checks structural CSV integrity but not domain-schema alignment. Added a 16-case unittest suite for core.py/design_system.py, which had zero test coverage.
• SKILL.md: replaced relative python3 skills/... invocations (wrong cwd assumption for a plugin install, and python3 doesn't exist on stock Windows) with ${CLAUDE_PLUGIN_ROOT}-anchored paths plus a python/python3/py fallback note; moved the ~250-line Quick Reference and App-UI pro-rules/checklist into references/quick-reference.md and references/pro-rules.md (loaded on demand), cutting SKILL.md from 703 to ~170 lines; fixed the documented --persist path to match the code (design-system/<slug>/MASTER.md, not design-system/MASTER.md); reconciled style/palette/font/product/stack counts against actual CSV row counts in SKILL.md, plugin.json, and README.md (several had drifted, e.g. "67 UI styles" -> 84, "161 palettes" -> 192).

Known follow-ups not addressed here

• README's "Available Styles (67)" curated breakdown list is stale relative to the 84 styles now in styles.csv (17 new styles were added without updating that categorized list). Left untouched since backfilling it accurately requires design judgment about category placement, not a mechanical fix.
• data/stacks/threejs.csv is missing the No index column present in every other stack CSV. Harmless for search (not part of any search/output column), flagged by the new validate_data.py.

Test plan

• bash scripts/smoke-domains.sh -- 12/12 domains OK
• bash scripts/smoke-stacks.sh -- 22/22 stacks OK
• python scripts/validate-csv.py -- passes
• node cli/scripts/sync-assets.mjs --check -- in sync (now covering .claude/skills/ too)
• python -m unittest discover -s src/ui-ux-pro-max/scripts/tests -- 16/16 passing
• python src/ui-ux-pro-max/scripts/validate_data.py -- 1 known finding (threejs.csv, noted above)
• Manually verified --design-system, --persist/--force, --json, zero-result suggestions, and all 22 stacks/12 domains via search.py directly

🤖 Generated with Claude Code

[jizc]

As the author of #242 (the .NET desktop stacks), I hit this exact bug: after a marketplace install, --stack wpf → Stack file not found. On main, .claude/skills/ui-ux-pro-max/data/stacks/ ships only 16 of the 22 registered stacks (missing javafx, wpf, winui, avalonia, uno, uwp) because sync + CI only covered cli/assets/. This fixes it and guards against regression. Confirmed the drift/sync part — LGTM. 👍

[clark-cant]

Thanks for the thorough work @sunilchandarjr — this PR addresses real drift issues we've been tracking (6 missing stacks in .claude/skills/ copy, stale CSVs, SKILL.md bloat). The test plan and detailed breakdown are excellent.

However, this PR has merge conflicts with main (mergeStateStatus=DIRTY) and no CI checks are running on this branch. Before I can do a proper deep review:

1. Please rebase onto current main — the base has moved since you opened this (notably after PR chore: repo health files, CI test wiring, and a real SVG bug fix #408 merge which added CI workflows and repo health files)
2. Verify CI passes after rebase — the check-asset-sync workflow should now cover the .claude/skills/ sync you extended

What looks good from the description:

• Sync tooling extension to cover .claude/skills/ — directly addresses the drift we flagged
• SKILL.md reduction from 703→170 lines via reference extraction — clean approach
• ${CLAUDE_PLUGIN_ROOT}-anchored paths — correct fix for plugin installs
• 16-case unittest suite — fills a real coverage gap
• validate_data.py — good complementary check

Will need verification after rebase:

• Whether the three-way sync (src/ ↔ cli/assets/ ↔ .claude/skills/) is consistent
• Whether the tokenizer stopword changes break any existing search behavior
• Count reconciliation across SKILL.md/plugin.json/README.md

Once rebased and CI is green, I'll do a full review. Marking as blocked until then.