@tw93/waza 3.25.0

package/skills/check/scripts/audit_signals.py

@@ -0,0 +1,485 @@
+#!/usr/bin/env python3
+"""Project audit signals (Phase 1) for /check audit mode.
+
+Walks a project root and emits 10 structured signal blocks to stdout.
+Each block ends with `status: PASS|WARN|FAIL` so the LLM driving the
+4-axis Linus-style scorecard can skim quickly.
+
+Pure stdlib. Read-only. Exits 0 even on WARN/FAIL so the harness does
+not confuse "finding surfaced" with "script broken".
+
+Run as: python3 skills/check/scripts/audit_signals.py --root <path>
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+
+EXCLUDED_DIRS = {
+    ".git", ".hg", ".svn", "node_modules", "dist", "build", ".next",
+    "__pycache__", ".turbo", "target", ".venv", "venv", "vendor",
+    "coverage", ".cache", ".parcel-cache", ".pytest_cache", ".mypy_cache",
+    ".ruff_cache", "Pods", "Carthage", ".swiftpm", ".gradle",
+}
+
+SOURCE_EXTS = {
+    ".py", ".swift", ".rs", ".go", ".ts", ".tsx", ".js", ".jsx", ".sh",
+    ".bash", ".zsh", ".rb", ".java", ".kt", ".m", ".mm", ".vue", ".c",
+    ".cc", ".cpp", ".h", ".hpp", ".cs",
+}
+
+HOTSPOT_LINES = 500
+HOTSPOT_FAIL = 1500
+HEREDOC_LINES = 100
+DRIFT_WARN = 50
+DRIFT_FAIL = 150
+DUP_JACCARD = 0.70
+
+MARKER_RE = re.compile(r"\b(TODO|FIXME|HACK|XXX)\b")
+HEREDOC_OPEN_RE = re.compile(
+    r"(python3?|node|ruby|perl|php)\b[^|\n]*?<<-?\s*['\"]?(\w+)['\"]?"
+)
+INSTALL_URL_RE = re.compile(
+    r"raw\.githubusercontent\.com/[^/\s]+/[^/\s]+/([^/\s]+)/"
+)
+# --exclude requires = or trailing value to avoid matching git's --exclude-standard
+DENYLIST_HINT_RE = re.compile(
+    r"(^\s*(skip|exclude)\s*=|\s--exclude=|!\*\.\w+|grep\s+-v\b|--ignore=)",
+    re.IGNORECASE,
+)
+MINIFIED_RE = re.compile(r"\.min\.[a-z]+$", re.IGNORECASE)
+
+
+def is_excluded(path: Path, root: Path) -> bool:
+    try:
+        parts = path.relative_to(root).parts
+    except ValueError:
+        parts = path.parts
+    if any(p in EXCLUDED_DIRS for p in parts):
+        return True
+    return bool(MINIFIED_RE.search(path.name))
+
+
+def iter_files(root: Path) -> list[Path]:
+    try:
+        proc = subprocess.run(
+            ["git", "-C", str(root), "ls-files",
+             "--cached", "--others", "--exclude-standard"],
+            text=True, stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL, check=False,
+        )
+        if proc.returncode == 0 and proc.stdout.strip():
+            out = []
+            for line in proc.stdout.splitlines():
+                p = root / line
+                if p.is_file() and not is_excluded(p, root):
+                    out.append(p)
+            return out
+    except OSError:
+        pass
+    out = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        current = Path(dirpath)
+        dirnames[:] = [d for d in dirnames if d not in EXCLUDED_DIRS]
+        if is_excluded(current, root):
+            continue
+        for fname in filenames:
+            p = current / fname
+            if p.is_file() and not is_excluded(p, root):
+                out.append(p)
+    return out
+
+
+def line_count(path: Path) -> int:
+    try:
+        with path.open("rb") as fh:
+            return sum(1 for _ in fh)
+    except OSError:
+        return 0
+
+
+def read_text(path: Path, limit: int = 0) -> str:
+    try:
+        data = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+    return data[:limit] if limit else data
+
+
+def rel(path: Path, root: Path) -> str:
+    try:
+        return path.relative_to(root).as_posix()
+    except ValueError:
+        return path.as_posix()
+
+
+def header(name: str) -> None:
+    print(f"=== {name} ===")
+
+
+def status(label: str) -> None:
+    print(f"status: {label}")
+
+
+def block_hotspots(files: list[Path], root: Path) -> None:
+    header("FILE SIZE HOTSPOTS")
+    big = sorted(
+        ((p, line_count(p)) for p in files
+         if p.suffix in SOURCE_EXTS and line_count(p) >= HOTSPOT_LINES),
+        key=lambda x: -x[1],
+    )[:10]
+    if not big:
+        print("(no source files >= 800 lines)")
+        status("PASS")
+        return
+    for path, n in big:
+        print(f"  {n:>5}  {rel(path, root)}")
+    if any(n >= HOTSPOT_FAIL for _, n in big):
+        status("FAIL")
+    elif len(big) > 3:
+        status("WARN")
+    else:
+        status("WARN")
+
+
+def block_heredoc(files: list[Path], root: Path) -> None:
+    header("HEREDOC BLOAT")
+    hits: list[tuple[str, int, str, int]] = []
+    for path in files:
+        if path.suffix not in {".sh", ".bash", ".zsh"}:
+            continue
+        text = read_text(path)
+        if not text:
+            continue
+        lines = text.splitlines()
+        i = 0
+        while i < len(lines):
+            m = HEREDOC_OPEN_RE.search(lines[i])
+            if not m:
+                i += 1
+                continue
+            lang, marker = m.group(1), m.group(2)
+            j = i + 1
+            close = re.compile(r"^\s*" + re.escape(marker) + r"\s*$")
+            while j < len(lines) and not close.match(lines[j]):
+                j += 1
+            size = j - i
+            if size >= HEREDOC_LINES:
+                hits.append((rel(path, root), i + 1, lang, size))
+            i = j + 1
+    if not hits:
+        print("(no python/node/ruby/perl/php heredocs >= 100 lines)")
+        status("PASS")
+        return
+    for f, ln, lang, sz in hits:
+        print(f"  {f}:{ln}  lang={lang}  block_lines={sz}")
+    status("WARN")
+
+
+def block_test_ci(files: list[Path], root: Path) -> None:
+    header("TEST AND CI SURFACE")
+    test_files = [
+        p for p in files
+        if p.suffix in SOURCE_EXTS
+        and (("test" in p.name.lower()) or ("spec" in p.name.lower()))
+    ]
+    src_files = [p for p in files if p.suffix in SOURCE_EXTS]
+    wf_dir = root / ".github" / "workflows"
+    workflows = []
+    if wf_dir.is_dir():
+        workflows = sorted(list(wf_dir.glob("*.yml")) + list(wf_dir.glob("*.yaml")))
+    job_names: list[str] = []
+    for wf in workflows:
+        text = read_text(wf, 50_000)
+        for m in re.finditer(r"^name:\s*(.+?)\s*$", text, re.MULTILINE):
+            job_names.append(f"{wf.name}: {m.group(1)[:60]}")
+            break
+    ratio = len(test_files) / max(len(src_files), 1)
+    print(f"tests_count={len(test_files)} source_count={len(src_files)} "
+          f"ratio={ratio:.1%}")
+    print(f"ci_workflow_files={len(workflows)}")
+    for j in job_names[:10]:
+        print(f"  workflow: {j}")
+    if not test_files and not workflows:
+        status("FAIL")
+    elif not test_files or not workflows:
+        status("WARN")
+    else:
+        status("PASS")
+
+
+def _grep_version(path: Path, pattern: str) -> str | None:
+    text = read_text(path, 20_000)
+    if not text:
+        return None
+    m = re.search(pattern, text, re.MULTILINE)
+    return m.group(1).strip() if m else None
+
+
+def block_version_sources(root: Path) -> None:
+    header("VERSION SOURCE COUNT")
+    found: list[tuple[str, str]] = []
+    v = root / "VERSION"
+    if v.is_file():
+        first = read_text(v).strip().splitlines()
+        if first:
+            found.append(("VERSION", first[0]))
+    probes = [
+        ("package.json", r'"version"\s*:\s*"([^"]+)"'),
+        ("Cargo.toml", r'^\s*version\s*=\s*"([^"]+)"'),
+        ("pyproject.toml", r'^\s*version\s*=\s*"([^"]+)"'),
+        ("setup.py", r"version\s*=\s*['\"]([^'\"]+)['\"]"),
+    ]
+    for fname, pat in probes:
+        p = root / fname
+        if p.is_file():
+            v_str = _grep_version(p, pat)
+            if v_str:
+                found.append((fname, v_str))
+    for pat in ("*.podspec", "*.csproj"):
+        for path in root.glob(pat):
+            v_str = _grep_version(
+                path, r'(?i)version\s*[:=]\s*["\']?(\d+\.\d+\.\d+[\w.-]*)'
+            )
+            if v_str:
+                found.append((path.name, v_str))
+    for path in list(root.glob("build.gradle*")):
+        v_str = _grep_version(
+            path, r'(?i)version\s*[:=]\s*["\']?(\d+\.\d+\.\d+[\w.-]*)'
+        )
+        if v_str:
+            found.append((path.name, v_str))
+    if not found:
+        print("(no declared version source found)")
+        status("PASS")
+        return
+    for f, val in found:
+        print(f"  {f}: {val}")
+    distinct = {val for _, val in found if val}
+    print(f"sources={len(found)} distinct_values={len(distinct)}")
+    if len(found) > 1 and len(distinct) > 1:
+        status("WARN")
+    else:
+        status("PASS")
+
+
+def block_packaging_posture(root: Path) -> None:
+    header("PACKAGING FILTER POSTURE")
+    allowlist_files = list(root.glob("*.allowlist")) + list(root.glob("MANIFEST.in"))
+    pkg_scripts = (list(root.glob("scripts/package*.sh"))
+                   + list(root.glob("scripts/release*.sh")))
+    denylist_hits = 0
+    for sp in pkg_scripts:
+        for line in read_text(sp).splitlines():
+            if DENYLIST_HINT_RE.search(line):
+                denylist_hits += 1
+    if allowlist_files:
+        for f in allowlist_files:
+            print(f"  allowlist: {rel(f, root)}")
+        print(f"posture=allowlist denylist_hits_in_scripts={denylist_hits}")
+        status("PASS")
+        return
+    if denylist_hits:
+        for sp in pkg_scripts:
+            print(f"  script: {rel(sp, root)}")
+        print(f"posture=denylist denylist_hits_in_scripts={denylist_hits}")
+        status("WARN")
+        return
+    print("posture=none (no packaging scripts)")
+    status("N/A")
+
+
+def block_install_url(root: Path) -> None:
+    header("INSTALL URL PINNING")
+    targets: list[Path] = [root / "README.md"]
+    targets += list(root.glob("scripts/setup*.sh"))
+    targets += list(root.glob("scripts/install*.sh"))
+    findings: list[tuple[str, int, str]] = []
+    for path in targets:
+        if not path.is_file():
+            continue
+        text = read_text(path, 200_000)
+        for i, line in enumerate(text.splitlines(), start=1):
+            for m in INSTALL_URL_RE.finditer(line):
+                findings.append((rel(path, root), i, m.group(1)))
+    if not findings:
+        print("(no raw.githubusercontent.com refs found)")
+        status("PASS")
+        return
+    moving = [f for f in findings if f[2] in ("main", "master", "HEAD")]
+    for f, ln, ref in findings[:20]:
+        marker = " [MOVING]" if ref in ("main", "master", "HEAD") else ""
+        print(f"  {f}:{ln}  ref={ref}{marker}")
+    print(f"total={len(findings)} moving={len(moving)}")
+    if moving:
+        status("WARN")
+    else:
+        status("PASS")
+
+
+def block_agent_doc_dedup(root: Path) -> None:
+    header("AGENT DOC DEDUP")
+    claude = root / "CLAUDE.md"
+    agents = root / "AGENTS.md"
+    have_c = claude.exists() or claude.is_symlink()
+    have_a = agents.exists() or agents.is_symlink()
+    if not have_c and not have_a:
+        print("posture=none")
+        status("PASS")
+        return
+    if not (have_c and have_a):
+        print(f"posture=single-file ({'CLAUDE.md' if have_c else 'AGENTS.md'} only)")
+        status("PASS")
+        return
+    if claude.is_symlink() and claude.resolve(strict=False).name == "AGENTS.md":
+        print("posture=symlink (CLAUDE.md -> AGENTS.md)")
+        status("PASS")
+        return
+    if agents.is_symlink() and agents.resolve(strict=False).name == "CLAUDE.md":
+        print("posture=symlink (AGENTS.md -> CLAUDE.md)")
+        status("PASS")
+        return
+    a = read_text(claude)
+    b = read_text(agents)
+    if a and a == b:
+        print("posture=identical (consider symlink to dedup)")
+        status("WARN")
+        return
+    cross = ("AGENTS.md" in a) or ("CLAUDE.md" in b)
+    a_set = {ln.strip() for ln in a.splitlines()
+             if ln.strip() and not ln.strip().startswith("#")}
+    b_set = {ln.strip() for ln in b.splitlines()
+             if ln.strip() and not ln.strip().startswith("#")}
+    union = a_set | b_set
+    jaccard = len(a_set & b_set) / len(union) if union else 0.0
+    print(f"jaccard={jaccard:.2f} cross_refs={cross}")
+    if jaccard >= 0.20:
+        print("posture=divergent-overlap (drift risk; consider symlink)")
+        status("WARN")
+        return
+    if cross:
+        print("posture=cross-ref (one references the other)")
+        status("WARN")
+        return
+    print("posture=independent")
+    status("PASS")
+
+
+def block_drift_markers(files: list[Path], root: Path) -> None:
+    header("DRIFT MARKERS")
+    counts: list[tuple[str, int]] = []
+    total = 0
+    for path in files:
+        if path.suffix not in SOURCE_EXTS:
+            continue
+        text = read_text(path, 200_000)
+        if not text:
+            continue
+        n = len(MARKER_RE.findall(text))
+        if n:
+            counts.append((rel(path, root), n))
+            total += n
+    counts.sort(key=lambda x: -x[1])
+    for f, n in counts[:5]:
+        print(f"  {n:>4}  {f}")
+    print(f"total={total}")
+    if total >= DRIFT_FAIL:
+        status("FAIL")
+    elif total >= DRIFT_WARN:
+        status("WARN")
+    else:
+        status("PASS")
+
+
+def block_duplicate_setup(root: Path) -> None:
+    header("DUPLICATE SETUP SCRIPTS")
+    scripts = (list(root.glob("scripts/setup-*.sh"))
+               + list(root.glob("scripts/install-*.sh")))
+    if len(scripts) < 2:
+        print("(fewer than 2 setup-* scripts to compare)")
+        status("N/A")
+        return
+    sets: dict[Path, set[str]] = {}
+    for sp in scripts:
+        sets[sp] = {ln.strip() for ln in read_text(sp).splitlines()
+                    if ln.strip() and not ln.strip().startswith("#")}
+    pairs: list[tuple[str, str, float]] = []
+    names = list(sets.keys())
+    for i, a in enumerate(names):
+        for b in names[i + 1:]:
+            union = sets[a] | sets[b]
+            if not union:
+                continue
+            j = len(sets[a] & sets[b]) / len(union)
+            if j >= DUP_JACCARD:
+                pairs.append((rel(a, root), rel(b, root), j))
+    if not pairs:
+        print("(no setup pairs with jaccard >= 0.70)")
+        status("PASS")
+        return
+    for a, b, j in pairs:
+        print(f"  {a} vs {b}  jaccard={j:.2f}")
+    status("WARN")
+
+
+def block_denylist_in_build(root: Path) -> None:
+    header("DENYLIST IN BUILD")
+    targets = (list(root.glob("scripts/package*.sh"))
+               + list(root.glob("scripts/release*.sh"))
+               + [root / "Makefile", root / "Justfile"])
+    real_targets = [p for p in targets if p.is_file()]
+    if not real_targets:
+        print("(no build scripts present)")
+        status("N/A")
+        return
+    hits: list[tuple[str, int, str]] = []
+    for path in real_targets:
+        text = read_text(path, 100_000)
+        for i, line in enumerate(text.splitlines(), start=1):
+            if DENYLIST_HINT_RE.search(line):
+                hits.append((rel(path, root), i, line.strip()[:80]))
+    if not hits:
+        print("(no denylist patterns found in build scripts)")
+        status("PASS")
+        return
+    for f, ln, s in hits[:20]:
+        print(f"  {f}:{ln}  {s}")
+    status("WARN")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--root", type=Path, default=Path.cwd(),
+        help="Project root to audit (default: current working directory)",
+    )
+    args = parser.parse_args()
+    root = args.root.resolve()
+    if not root.is_dir():
+        print(f"audit_signals: not a directory: {root}", file=sys.stderr)
+        return 2
+    files = iter_files(root)
+    print(f"project_root: {root}")
+    print(f"files_scanned: {len(files)}")
+    print()
+    block_hotspots(files, root); print()
+    block_heredoc(files, root); print()
+    block_test_ci(files, root); print()
+    block_version_sources(root); print()
+    block_packaging_posture(root); print()
+    block_install_url(root); print()
+    block_agent_doc_dedup(root); print()
+    block_drift_markers(files, root); print()
+    block_duplicate_setup(root); print()
+    block_denylist_in_build(root)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/check/scripts/run-tests.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Auto-detect and run project verification (lint + typecheck + tests).
+# Run from the project root. Exits non-zero on failure.
+set -euo pipefail
+
+if [ -f Cargo.toml ]; then
+  cargo check && cargo test
+elif [ -f tsconfig.json ]; then
+  npx tsc --noEmit && npm test
+elif [ -f package.json ] && grep -q '"test"' package.json; then
+  npm test
+elif [ -f Makefile ] && grep -q '^test:' Makefile; then
+  make test
+elif [ -f pytest.ini ] || [ -f pyproject.toml ] || find . -maxdepth 2 -name "test_*.py" | grep -q .; then
+  pytest
+else
+  echo "(no test command detected - ask the user for the verification command)"
+  exit 1
+fi

package/skills/design/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: design
+description: "Produces distinctive, production-grade UI for pages, components, visual interfaces, typography, and screenshot-driven polish. Use when users ask 设计/做页面/做组件/UI/前端/截图 or say a screen is ugly, unclear, inconsistent, or visually wrong. Not for backend logic or data pipelines."
+when_to_use: "设计, 做页面, 做组件, 不好看, 不和谐, 不清晰, 很丑, 很怪, 很傻, 突兀, 不协调, 字体, 字形, 排印, 排版, 样式, 前端, UI, 截图, build page, create component, make it look good, style, design, screenshot with visual complaint, typography, font looks wrong"
+dispatch_intent: "UI, component, page, visual interface, frontend, artifact-grounded screenshot aesthetic complaint"
+---
+
+# Design: Build It With a Point of View
+
+Prefix your first line with 🥷 inline, not as its own paragraph.
+
+If it could have been generated by a default prompt, it is not good enough.
+
+**Output language rule:** Never use em-dash (—) in any output from this skill. Use commas, colons, or periods instead.
+
+**Chinese gut-feel complaints**: when the user says "很傻", "很怪", "突兀", "不协调", "不和谐" about a visual, treat it as an aesthetic rejection, not a debugging symptom. Route to Screenshot Iteration Mode, not to `/hunt`.
+
+## Durable Context Preflight
+
+See [rules/durable-context.md](../../rules/durable-context.md) for when to read durable context, the read-order budget, and the memory-type mapping.
+
+For `/design`, visual constraints are `decision`, `preference`, and `principle` entries; reusable product and UI patterns are `pattern` and `learning`. Current screenshots, rendered output, code, design tokens, and user feedback override memory. Reuse durable visual preferences and mature interaction patterns, but still name the current visual problem from the screenshot or source before changing code.
+
+## Screenshot Iteration Mode
+
+Activate when the user sends a screenshot or image alongside a complaint ("这里很丑", "这个不对", "fix this", "looks wrong"). The existing product is the direction. Skip the five-question direction lock.
+
+**Flow:**
+
+1. Read the screenshot. State the problem in one sentence: what specifically looks wrong (spacing, contrast, alignment, typeface, color, density, hierarchy). Preserve the user's negative label when it is diagnostic; do not translate "丑", "乱", "不清晰", or "怪" into vague "make it modern" language.
+2. Wait for the user to confirm the diagnosis before touching code.
+3. If the user provides a reference screenshot, older version, or "this one is good" example, compare current vs. reference and name the visual deltas before choosing a fix.
+4. If the diagnosis is a known UX problem (split-view sync, infinite scroll, virtualised list, sticky header), spend one round surveying how 2-3 mature products in the same category solve it before writing code. Cite what each does. Skip only if the fix is purely cosmetic (color, spacing, copy).
+5. Find the responsible code: grep for the component name or class, read the actual file. Do not rely on memory or assumptions about file location.
+6. Apply the minimal fix. For existing products, try material/opacity, geometry, spacing, typography, or text-fit adjustments before redesigning the surface.
+7. Verify the result in a browser, native app, screenshot tool, or rendered artifact at desktop width and 375px mobile width when applicable. Check long words, localized strings, button labels, and compact states for overflow. If the host cannot render, say that explicitly and hand off the exact view the user should check.
+8. Ask the user to verify in the browser. Do not hand off without this step.
+
+**Calibration rules:**
+- The user's screenshot is the strongest design brief in the turn. Keep it visible in the reasoning until the fix is done.
+- The real running product is the oracle. Product pages, app screenshots, release pages, and current UI state override generic style instincts.
+- Do not flatten specific taste feedback into generic UI adjectives. "More premium" is not a diagnosis; "caption baseline drifts above the Chinese line" is.
+- If the screenshot exposes a regression, broken render, timing issue, or generated asset defect rather than taste, route to `/hunt` and preserve the visual evidence.
+
+**Boundary**: if the fix requires changing 3 or more components, or if it reveals a direction problem rather than a specific bug, pause and run the full direction lock before continuing.
+
+**Redesign priority order** (when reworking an existing UI rather than building from scratch): font replacement → color cleanup → hover/active states → layout and whitespace → replace generic components → add loading/empty/error states → typographic polish. This order maximizes visual lift while minimizing the blast radius of each pass. Full rules in `references/design-reference.md`. Common traps and absolute CSS bans: `references/design-traps.md`.
+
+## Lock the Direction First
+
+**Before starting any component, page, or visual work**: list 2-3 mature products in the same category (e.g. Notion, Linear, Typora, iA Writer, Raycast), and write one sentence each on how they solve the specific problem at hand. Then write code. Skip only if the task is purely cosmetic (color, spacing, copy).
+
+Before writing any code, ask the user directly, using the environment's native question or approval mechanism if it has one:
+
+1. **Who uses this, and in what context?** Analyst dashboard differs from landing page or onboarding flow. See "App shell exception" below if the answer is a sidebar + main workspace layout.
+2. **What is the aesthetic direction?** Name it precisely: dense editorial, raw terminal, ink-on-paper, brutalist grid, warm analog. "Clean and modern" is not a direction. If the user names a reference site or product ("feels like Linear / Claude.ai / Vercel"), do not accept it as a direction -- extract 3 concrete properties from it: button radius philosophy, surface depth treatment (shadow vs background step vs border), and accent color family. Name those instead.
+
+   **Shortcut for well-known brands**: see "Brand preset flow" in `references/design-reference.md`. Ask first, run the preset, then decompose against the generated file.
+3. **What is the one thing this leaves in memory?** A typeface, color system, unexpected motion, asymmetric layout. Pick one and make it obvious.
+4. **What are the hard constraints?** Framework, bundle size, contrast minimums, keyboard accessibility.
+5. **What is the signature micro-interaction?** Scale on press, staggered reveal, or contextual icon animation. Pick one and know exactly how it's implemented.
+
+Do not proceed until all five are answered.
+
+### Source repo as reference
+
+When the user provides a repository URL or pastes source code of an existing product to recreate or extend: the file tree is a menu, not the meal. Do not reconstruct the UI from memory or training data. Instead, read the actual source:
+- Theme and token files: `theme.ts`, `colors.ts`, `tokens.css`, `_variables.scss`, or equivalent
+- Global stylesheets and layout scaffolds
+- The specific components the user mentioned
+
+Lift exact values: hex codes, spacing scale entries, font stacks, border radii. A rough approximation is not pixel fidelity.
+
+Only attach the target component folder or package. Exclude `.git`, `node_modules`, `dist`, and lock files. Dragging in an entire monorepo pollutes the context with irrelevant code and degrades output quality.
+
+### App shell exception (sidebar + main workspace)
+
+If question 1 is an app shell (Slack, Linear, Notion class), load the "App shell rules" section in `references/design-reference.md` and apply those constraints before proceeding.
+
+### Data dashboard exception
+
+If the surface is a dashboard, analytics view, or chart-heavy interface, also load `references/design-data-viz.md` for chart selection, number alignment, and product-benchmark rules. Skip when building marketing pages, landing pages, or generic components.
+
+State the chosen direction in one sentence, then load `references/design-reference.md` and check the tech stack conflicts table. Name the single CSS strategy before writing the first component. For token decisions (color, font, motion): load `references/design-tokens.md`. For aesthetic quality review and production structure: load `references/design-aesthetic-quality.md`.
+
+Summarize the direction as three lines before writing any code:
+- **Visual thesis**: mood, material, and energy in one sentence (e.g. "warm brutalist editorial with high-contrast ink type and rough paper texture")
+- **Content plan**: hero -> support -> detail -> final CTA, one line each. For **app/dashboard surfaces**: skip the marketing structure, default to utility mode (orient, show status, enable action), no hero unless explicitly requested.
+- **Interaction thesis**: 2-3 specific motion ideas that change how the page feels (e.g. "hero text slides in on load, section headers pin while content scrolls beneath, CTA pulses on hover")
+
+For production or multi-page UIs, expand the thesis into the 9-section DESIGN.md scaffold in `references/design-reference.md` (theme, palette, typography, components, layout, depth, do/don't, responsive, prompt guide). For a single component, the three lines are sufficient.
+
+## Non-Negotiable Constraints
+
+`references/design-reference.md` is already loaded during direction lock. It owns the full rules: typography, OKLCH color, motion timings, layout defaults, CSS-pattern bans, accessibility baseline, and complexity matching. Apply them. Do not restate them here.
+
+## When Asked For Options
+
+Give at least 3 variations across genuinely different dimensions (density, typography, color, layout, motion). See "Options guide" in `references/design-reference.md` for the full variation framework. Three options differing only by accent color are not three variations.
+
+## Gotchas
+
+| What happened | Rule |
+|---------------|------|
+| Used Inter as the display font | It communicates nothing. Pick something with a personality. |
+| Three cards, identical shadows, identical padding -- a template | If swapping content doesn't require layout changes, redo it. |
+| Claimed it looked right without opening a browser | Code correct in your head can look broken in the browser. Open it. |
+| Chose glassmorphism, ignored the mobile constraint | `backdrop-filter` is expensive on low-power devices. Name the tradeoff. |
+| Light-mode app: white panel on white background, visually indistinguishable | Adjacent nested surfaces must differ visually. Either background step (sidebar vs main ≥4% lightness difference) or shadow minimum `0 1px 3px rgba(0,0,0,0.10)`. |
+| Fixed visual polish by redesigning the whole surface | Locate the concrete visual delta first, then make the smallest material, opacity, geometry, or typography change that addresses it. |
+| English looked fine, localized text overflowed | Test long words and localized strings before handoff, especially inside buttons, tabs, nav, and compact cards. |
+
+## Aesthetic Review
+
+After significant build phases and at handoff, re-read the visual thesis from direction lock. If what is on screen drifted toward a generic default, identify the specific element that broke first (typeface, color, card treatment, spacing) and fix it before continuing.
+
+Run these checks before the handoff summary:
+- Is the brand or product unmistakable in the first screen?
+- Is there one strong visual anchor (real imagery, not a decorative gradient)?
+- Can the page be understood by scanning headlines only?
+- Does each section have one job?
+- Are cards actually necessary, or just default styling?
+- Does motion improve hierarchy or atmosphere, or is it ornamental?
+- Would the design still feel premium if all decorative shadows were removed?
+- AI Slop Test: scan the first screen for default patterns (reflex font, purple-to-blue gradient, centered hero with two CTAs side by side, three identical cards, generic top nav). If any appear unintentionally, fix typography, color, or layout until none remain.
+
+If any check fails, fix first. Ask the user to verify at full width and at 375px; if the layout breaks at mobile width, fix before handing off.
+
+End with:
+- Aesthetic direction, named and justified in 2-3 sentences
+- Non-obvious choices explained: typeface, color decisions, layout logic
+- Instructions for replacing placeholder content with real content
+
+After handoff, stop.