@ericrisco/rsc 1.0.33 → 1.1.0

package/skills/design-dna/scripts/emit.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""Scaffold and validate an emitted style skill (design-dna Step 6).
+
+    python3 emit.py <slug>              scaffold ~/.claude/skills/<slug>/ from templates
+    python3 emit.py <slug> --validate   validate an existing one, exit non-zero on failure
+
+Validation enforces the rules that are the whole point of the method, so a
+half-finished capture cannot pass itself off as a skill:
+  - dna.json parses and satisfies design-dna.schema.json (required keys, bounds)
+  - signatures: 3 to 9        - bans: 5 or more (as absolutes)
+  - tests: 8 or more          - reconstruction.attempted is true (Step 5 was run)
+  - PROMPT.md is at most 2048 bytes and ends with the self-check line
+  - reference/ is not empty (the image is mandatory)
+"""
+import json, os, re, shutil, sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+PARENT = os.path.dirname(HERE)
+SKILLS = os.path.dirname(PARENT)
+CAP = 2048
+LAST_LINE = "Before returning any output, run every test in the self-check."
+
+REQUIRED_TOP = ["meta", "soul", "palette", "type", "space", "signatures",
+                "weird_move", "bans", "tests", "reconstruction"]
+
+
+def scaffold(slug):
+    dest = os.path.join(SKILLS, slug)
+    if os.path.exists(dest):
+        sys.exit(f"refusing to overwrite {dest} - one skill per style, and this one exists")
+    for sub in ("reference", "example", "scripts"):
+        os.makedirs(os.path.join(dest, sub))
+    for src, dst in (("templates/SKILL.md.tmpl", "SKILL.md"),
+                     ("templates/PROMPT.md.tmpl", "PROMPT.md"),
+                     ("templates/check.py.tmpl", "scripts/check.py")):
+        shutil.copy(os.path.join(PARENT, src), os.path.join(dest, dst))
+    os.chmod(os.path.join(dest, "scripts/check.py"), 0o755)
+    shutil.copy(os.path.join(PARENT, "design-dna.schema.json"),
+                os.path.join(dest, "design-dna.schema.json"))
+    print(f"scaffolded {dest}")
+    print("next: write dna.json, fill the __PLACEHOLDERS__, drop the reference image in reference/,")
+    print(f"      build one worked output into example/, then: python3 {__file__} {slug} --validate")
+
+
+def fail(errs, slug):
+    for e in errs:
+        print(f"  FAIL  {e}")
+    print(f"\n{len(errs)} problem(s). {slug} is not a finished skill yet.")
+    return 1
+
+
+def validate(slug):
+    d = os.path.join(SKILLS, slug)
+    errs = []
+    if not os.path.isdir(d):
+        sys.exit(f"no such skill: {d}")
+
+    dna_path = os.path.join(d, "dna.json")
+    dna = None
+    if not os.path.isfile(dna_path):
+        errs.append("dna.json missing")
+    else:
+        try:
+            dna = json.load(open(dna_path))
+        except json.JSONDecodeError as e:
+            errs.append(f"dna.json does not parse: {e}")
+
+    if dna:
+        for k in REQUIRED_TOP:
+            if k not in dna:
+                errs.append(f"dna.json missing required key: {k}")
+        sigs = dna.get("signatures", [])
+        if not 3 <= len(sigs) <= 9:
+            errs.append(f"signatures must be 3-9, found {len(sigs)} (the cap forces a decision)")
+        for s in sigs:
+            for f in ("move", "how", "when", "never"):
+                if not s.get(f):
+                    errs.append(f"signature {s.get('move', '?')!r} missing {f}")
+        bans = dna.get("bans", [])
+        if len(bans) < 5:
+            errs.append(f"bans must be 5 or more, found {len(bans)}")
+        if len(bans) < len(sigs):
+            errs.append("bans should outnumber positive style rules; they do the heavy lifting")
+        tests = dna.get("tests", [])
+        if len(tests) < 8:
+            errs.append(f"tests must be 8 or more, found {len(tests)}")
+        for t in tests:
+            for f in ("id", "check", "fail_looks_like"):
+                if not t.get(f):
+                    errs.append(f"test {t.get('id', '?')!r} missing {f}")
+            if "auto" not in t:
+                errs.append(f"test {t.get('id', '?')!r} must declare auto: true|false")
+        vague = [t["id"] for t in tests if re.search(
+            r"\b(feels?|looks? (clean|premium|nice|good)|elegant|modern|polished)\b",
+            t.get("check", ""), re.I)]
+        if vague:
+            errs.append(f"not tests, two people could disagree: {vague}")
+        rec = dna.get("reconstruction", {})
+        if not rec.get("attempted"):
+            errs.append("reconstruction.attempted is false: Step 5 was skipped, so the spec is untested")
+        elif not rec.get("gaps_found"):
+            errs.append("reconstruction.gaps_found is empty: a first rebuild that found nothing means "
+                        "you did not really close the reference")
+        cov = dna.get("palette", {}).get("coverage") or {}
+        if not cov:
+            errs.append("palette.coverage missing: the most-skipped and most-decisive field")
+        elif not 90 <= sum(float(v) for v in cov.values()) <= 110:
+            errs.append(f"palette.coverage sums to {sum(float(v) for v in cov.values())}, expected ~100")
+        for c in dna.get("palette", {}).get("colors", []):
+            if re.match(r"^[a-z]+-\d{2,3}$", str(c.get("name", ""))):
+                errs.append(f"colour name {c['name']!r} is systematic; image models cannot read token "
+                            "names. Use a descriptive name.")
+        for f in dna.get("type", {}).get("families", []):
+            if not f.get("fallback"):
+                errs.append(f"type family {f.get('family', '?')!r} has no fallback: silent Arial "
+                            "substitution is how a reproduction dies quietly")
+        sp = dna.get("space", {})
+        if isinstance(sp.get("margin_pct"), str) and "px" in sp["margin_pct"]:
+            errs.append("space uses pixels; percentages are what let one spec drive a carousel and a slide")
+
+    p = os.path.join(d, "PROMPT.md")
+    if not os.path.isfile(p):
+        errs.append("PROMPT.md missing")
+    else:
+        raw = open(p, "rb").read()
+        body = re.sub(rb"<!--.*?-->", b"", raw, flags=re.S).strip()
+        if len(body) > CAP:
+            errs.append(f"PROMPT.md is {len(body)}B of payload, cap is {CAP}B. Cut, do not negotiate.")
+        txt = body.decode("utf-8", "replace")
+        if LAST_LINE not in txt:
+            errs.append("PROMPT.md does not end with the mandatory self-check line")
+        if "__" in txt:
+            errs.append("PROMPT.md still contains __PLACEHOLDERS__")
+        if "dna.json" in txt:
+            errs.append("PROMPT.md references dna.json; the record never enters a prompt")
+
+    ref = os.path.join(d, "reference")
+    if not os.path.isdir(ref) or not os.listdir(ref):
+        errs.append("reference/ is empty. The image is mandatory and close to free.")
+    ex = os.path.join(d, "example")
+    if not os.path.isdir(ex) or not os.listdir(ex):
+        errs.append("example/ is empty. One worked output is the canonical proof.")
+    s = os.path.join(d, "SKILL.md")
+    if not os.path.isfile(s):
+        errs.append("SKILL.md missing")
+    elif "__" in open(s).read():
+        errs.append("SKILL.md still contains __PLACEHOLDERS__")
+
+    if errs:
+        return fail(errs, slug)
+    print(f"  PASS  {slug} is a finished style skill.")
+    print(f"        signatures {len(dna['signatures'])}, bans {len(dna['bans'])}, "
+          f"tests {len(dna['tests'])}, reconstruction passes {dna['reconstruction'].get('passes', '?')}")
+    return 0
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print(__doc__)
+        sys.exit(2)
+    slug = sys.argv[1]
+    if not re.fullmatch(r"[a-z0-9]+(-[a-z0-9]+)*", slug):
+        sys.exit("slug must be kebab-case")
+    sys.exit(validate(slug) if "--validate" in sys.argv else (scaffold(slug) or 0))

package/skills/design-dna/templates/PROMPT.md.tmpl

@@ -0,0 +1,42 @@
+<!-- __NAME__ - the payload. HARD CAP 2KB of text.
+     Order is fixed: attention is strongest at both ends, weakest in the middle.
+     To add a tenth signature you must delete one. dna.json never goes in here. -->
+
+# Style: __NAME__
+
+**Reference image: `reference/__REF__` - attached. Match it before you match these words.**
+
+**Soul.** __ONE_LINE__
+
+## The weird move (present exactly once, never twice)
+
+__WEIRD_MOVE__
+
+## Signature moves (as ratios)
+
+1. __SIG_1__
+2. __SIG_2__
+3. __SIG_3__
+
+## Never
+
+- __BAN_1__
+- __BAN_2__
+- __BAN_3__
+- __BAN_4__
+- __BAN_5__
+
+## Palette and type (roles and coverage only)
+
+__PALETTE_LINE__
+__TYPE_LINE__
+
+## Layouts
+
+__ARCHETYPE_LINES__
+
+## Self-check
+
+__TEST_LINES__
+
+Before returning any output, run every test in the self-check. Name each test and its result. If any fails, repair the output and run them again. Never return output with a failing test and a note explaining it away.

package/skills/design-dna/templates/SKILL.md.tmpl

@@ -0,0 +1,42 @@
+---
+name: __SLUG__
+description: "Use when building anything in the __NAME__ style: __ONE_LINE__ Fires on '__SLUG__', 'in the __NAME__ style', 'another one like <reference>', 'same look as before'. Captured from __MEDIUM__; drives any format. NOT inventing a new direction (that is `design`), NOT re-deriving this style (its record already exists in dna.json)."
+tags: [style, design-dna, __SLUG__]
+recommends: [design-dna, nextjs, marketing]
+origin: design-dna
+---
+
+# __NAME__
+
+*__ONE_LINE__*
+
+Captured __CAPTURED__ from __MEDIUM__. Reference kept in `reference/`. Worked proof in `example/`.
+
+## How to use this
+
+1. Load **`PROMPT.md` only**, and attach `reference/__REF__`. Never paste `dna.json` into a prompt: it is the record, not the payload, and its size is exactly what breaks compliance.
+2. Pick an archetype by name before writing a line. Structure first, or piece 8 will not sit beside piece 1 as a set.
+3. Build. Web build goes to `../nextjs/SKILL.md`, words to `../marketing/SKILL.md`; the identity stays here.
+4. Run the self-check. Name every test and its result:
+
+       python3 scripts/check.py <output files or a rendered PNG>
+
+   Non-zero exit means do not ship. Answer the MANUAL tests out loud.
+
+## What this style is, in one screen
+
+__SUMMARY__
+
+## Do not
+
+__BANS__
+
+## Known drift risks
+
+__CONFIDENCE__
+
+These are the values that were inferred rather than measured. If output starts feeling off, re-measure these first.
+
+## Maintenance
+
+Re-capture only when the reference itself changes. To extend the style, edit `dna.json`, then recompile `PROMPT.md` under the 2KB cap: adding a signature means deleting one. Method and rationale: `../design-dna/SKILL.md`.

package/skills/design-dna/templates/check.py.tmpl

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Auto tests for the __NAME__ style. Exits non-zero on any failure.
+
+    python3 scripts/check.py <output.html|output.css|output.png> [more files...]
+
+Reads dna.json and runs every test marked "auto": true that carries a "probe".
+Tests without a probe are reported as MANUAL and never silently pass.
+A probe handed no artefact it can read is reported as SKIP with its reason -
+never as PASS or FAIL.
+
+Probe kinds
+-----------
+regex_absent        {"kind":"regex_absent","pattern":"..."}                 fails if the pattern appears
+regex_count         {"kind":"regex_count","pattern":"...","exactly":1}      or "min"/"max"
+distinct_css        {"kind":"distinct_css","property":"font-size","max":3}  distinct declared values
+css_ratio           {"kind":"css_ratio","property":"font-size","min":6.0}   largest / smallest declared
+min_unit            {"kind":"min_unit","property":"font-size","min_px":28}  smallest declared value
+color_coverage      {"kind":"color_coverage","hex":"#ff4d00","max_pct":8,
+                     "tolerance":24}                                        needs an image file + Pillow
+"""
+import json, os, re, sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+DNA_PATH = os.path.join(HERE, "..", "dna.json")
+if not os.path.isfile(DNA_PATH):
+    sys.exit("no dna.json beside this script, so there is nothing to check against.\n"
+             "This style skill was scaffolded and never finished. Fix:\n"
+             "  write dna.json, then validate it with\n"
+             "  python3 ../design-dna/scripts/emit.py <slug> --validate")
+DNA = json.load(open(DNA_PATH))
+
+TEXT_EXT = {".html", ".htm", ".css", ".scss", ".jsx", ".tsx", ".svg", ".md", ".js", ".ts"}
+IMG_EXT = {".png", ".jpg", ".jpeg", ".webp"}
+
+
+def load(paths):
+    text, images = "", []
+    for p in paths:
+        ext = os.path.splitext(p)[1].lower()
+        if ext in IMG_EXT:
+            images.append(p)
+        elif ext in TEXT_EXT or os.path.isfile(p):
+            text += "\n" + open(p, encoding="utf-8", errors="replace").read()
+    return text, images
+
+
+def css_values(text, prop):
+    out = []
+    for raw in re.findall(rf"{re.escape(prop)}\s*:\s*([^;}}\"']+)", text, re.I):
+        m = re.match(r"\s*(-?[\d.]+)\s*(px|rem|em|pt|%)?", raw)
+        if not m:
+            continue
+        n = float(m.group(1))
+        unit = (m.group(2) or "px").lower()
+        out.append(n * 16 if unit in ("rem", "em") else n)
+    return out
+
+
+def coverage(path, hex_target, tol):
+    try:
+        from PIL import Image
+    except ImportError:
+        return None, "Pillow not installed (pip install pillow)"
+    tr, tg, tb = (int(hex_target.lstrip("#")[i:i + 2], 16) for i in (0, 2, 4))
+    im = Image.open(path).convert("RGB")
+    im.thumbnail((400, 400))
+    px = list(im.get_flattened_data()) if hasattr(im, "get_flattened_data") else list(im.getdata())
+    hit = sum(1 for r, g, b in px if abs(r - tr) <= tol and abs(g - tg) <= tol and abs(b - tb) <= tol)
+    return 100.0 * hit / max(1, len(px)), None
+
+
+# Probes that read declared values. Handed no text they must SKIP: a regex over an empty
+# string is not a check, and calling it PASS or FAIL is the gate lying in one direction
+# or the other.
+TEXT_PROBES = ("regex_absent", "regex_count", "distinct_css", "css_ratio", "min_unit")
+
+
+def run(test, text, images):
+    pr = test.get("probe")
+    if not pr:
+        return "MANUAL", "no probe declared"
+    k = pr.get("kind")
+    if k in TEXT_PROBES and not text.strip():
+        return "SKIP", "no text artefact passed; this probe reads declarations, not pixels"
+    if k == "regex_absent":
+        hits = re.findall(pr["pattern"], text, re.I)
+        return ("FAIL" if hits else "PASS"), f"{len(hits)} match(es)"
+    if k == "regex_count":
+        n = len(re.findall(pr["pattern"], text, re.I))
+        ok = (n == pr["exactly"]) if "exactly" in pr else (pr.get("min", 0) <= n <= pr.get("max", 10 ** 9))
+        return ("PASS" if ok else "FAIL"), f"found {n}"
+    if k == "distinct_css":
+        vals = sorted(set(css_values(text, pr["property"])))
+        return ("PASS" if len(vals) <= pr["max"] else "FAIL"), f"{len(vals)} distinct: {vals}"
+    if k == "css_ratio":
+        vals = [v for v in css_values(text, pr["property"]) if v > 0]
+        if not vals:
+            return "SKIP", f"no {pr['property']} declarations found"
+        r = max(vals) / min(vals)
+        return ("PASS" if r >= pr["min"] else "FAIL"), f"ratio {r:.2f}:1"
+    if k == "min_unit":
+        vals = [v for v in css_values(text, pr["property"]) if v > 0]
+        if not vals:
+            return "SKIP", f"no {pr['property']} declarations found"
+        return ("PASS" if min(vals) >= pr["min_px"] else "FAIL"), f"smallest {min(vals)}px"
+    if k == "color_coverage":
+        if not images:
+            return "SKIP", "no image passed; render the output to PNG to check coverage"
+        pct, err = coverage(images[0], pr["hex"], pr.get("tolerance", 24))
+        if err:
+            return "SKIP", err
+        lo, hi = pr.get("min_pct", 0), pr.get("max_pct", 100)
+        return ("PASS" if lo <= pct <= hi else "FAIL"), f"{pct:.1f}% of canvas"
+    return "SKIP", f"unknown probe kind {k!r}"
+
+
+def main():
+    if len(sys.argv) < 2:
+        print(__doc__)
+        return 2
+    text, images = load(sys.argv[1:])
+    failed = manual = 0
+    print(f"design-dna check: {DNA['meta']['name']}\n")
+    for t in DNA.get("tests", []):
+        if not t.get("auto"):
+            status, detail = "MANUAL", "human judgement"
+        else:
+            status, detail = run(t, text, images)
+        failed += status == "FAIL"
+        manual += status == "MANUAL"
+        print(f"  [{status:6}] {t['id']:28} {t['check']}")
+        if detail:
+            print(f"            {detail}")
+        if status == "FAIL":
+            print(f"            fail looks like: {t['fail_looks_like']}")
+    print(f"\n{failed} failed, {manual} need human judgement.")
+    if manual:
+        print("Answer the MANUAL tests out loud before you call this done.")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())