Merge pull request #10 from pavelevgrafov/fix-d41-tailwind-optional

Fix D.41 over-reach: the Tailwind bridge is optional, the CSS is not

Author: pavelevgrafov

.agents/skills/visual-director/scripts/compile-tokens.py

@@ -149,14 +149,28 @@ def first_difference(have, want):
 def main():
     ap = argparse.ArgumentParser()
     ap.add_argument("tokens", nargs="?", default="tokens.json")
-    ap.add_argument("--out-css", default="tokens.css")
-    ap.add_argument("--out-tailwind", default="tokens.theme.css")
+    ap.add_argument("--out-css", default=None)
+    ap.add_argument("--out-tailwind", default=None)
     ap.add_argument("--check-only", action="store_true")
     ap.add_argument("--verify", action="store_true",
                     help="D.41: fail if the files on disk differ from what "
                          "this run would write")
     args = ap.parse_args()
 
+    # --verify against the DEFAULT paths compares the tokens with whatever
+    # happens to sit in the working directory, and reports "missing" when
+    # nothing does. That reads exactly like real staleness and is not — it cost
+    # a reviewer a diff hunt on the day D.41 shipped. The floor always passes
+    # explicit paths, so requiring them costs nothing and removes the false
+    # alarm entirely.
+    if args.verify and not (args.out_css and args.out_tailwind):
+        print("FAIL: --verify needs explicit --out-css and --out-tailwind. "
+              "Comparing against the defaults would measure the working "
+              "directory, not the theme that belongs to these tokens.")
+        return 2
+    args.out_css = args.out_css or "tokens.css"
+    args.out_tailwind = args.out_tailwind or "tokens.theme.css"
+
     problems = []
     try:
         with open(args.tokens, encoding="utf-8") as f:
@@ -235,23 +249,37 @@ def main():
         return 1
 
     if args.verify:
-        stale = []
-        for path, want in ((args.out_css, css), (args.out_tailwind, tw)):
+        # The CSS is what the floor reads and what the browser renders, so its
+        # absence IS staleness. The Tailwind bridge is optional: a project that
+        # does not use Tailwind never emits one, and demanding it would fail
+        # every such project for a file it has no use for. Absent is reported,
+        # never silently treated as fresh [A.6]; present is always compared.
+        stale, notes = [], []
+        checked = 0
+        for path, want, required in ((args.out_css, css, True),
+                                     (args.out_tailwind, tw, False)):
             try:
                 with open(path, encoding="utf-8") as f:
                     have = f.read()
             except FileNotFoundError:
-                stale.append(f"{path}: missing — the theme was never compiled")
+                if required:
+                    stale.append(f"{path}: missing — the theme was never compiled")
+                else:
+                    notes.append(f"{path}: absent — no Tailwind bridge in this "
+                                 f"project, nothing to go stale")
                 continue
+            checked += 1
             if have != want:
                 stale.append(f"{path}: {first_difference(have, want)}")
+        for n in notes:
+            print(f"note: {n}")
         for s in stale:
             print(f"FAIL: {s}")
         if stale:
             print(f"\n{len(stale)} compiled file(s) no longer match {args.tokens} "
                   f"[D.41]. Re-run compile-tokens.py; never hand-edit the output.")
             return 1
-        print(f"OK: compiled theme matches {args.tokens} [D.41]")
+        print(f"OK: {checked} compiled file(s) match {args.tokens} [D.41]")
         return 0
 
     if args.check_only:

.github/workflows/design-ops.yml

@@ -85,7 +85,11 @@ jobs:
             --out /tmp/e2e/site --ux-out /tmp/e2e/artifacts/ux \
             --contract /tmp/e2e/artifacts/design-contract.yaml
           grep -q "origin: inherited" /tmp/e2e/artifacts/design-contract.yaml
-          cp skins/base-site/tokens.json skins/base-site/tokens.css /tmp/e2e/artifacts/visual/
+          # all three files a real K2A leaves behind, not two of them:
+          # a materialisation thinner than the real thing makes the floor
+          # measure a project that never exists (D.41 caught this)
+          cp skins/base-site/tokens.json skins/base-site/tokens.css \
+             skins/base-site/tokens.theme.css /tmp/e2e/artifacts/visual/
           cp skins/base-site/tokens.css /tmp/e2e/site/tokens.css
           sed -i 's|\.\./\.\./\.\./skins/base-site/tokens.css|tokens.css|' /tmp/e2e/site/index.html
       - name: Self-service panel on the real build

eval/selftest/run-self-test.sh

@@ -442,6 +442,19 @@ for SKIN in base-site base-app; do
 done
 [ "$D41BAD" -eq 0 ] && ok "D.41: both skins ship a fresh theme, and one edited line fails the build"
 
+# The Tailwind bridge is optional; the CSS is not. A project that never emits
+# a bridge must pass, and a project missing the CSS itself must not — the
+# post-merge run on main failed on exactly this over-reach, because the CI
+# materialisation copied two of the three files a real K2A leaves behind.
+D41OPT=$(mktemp -d 2>/dev/null || mktemp -d -t d41o)
+cp "$ROOT/skins/base-site/tokens.json" "$ROOT/skins/base-site/tokens.css" "$D41OPT/"
+python3 "$VD/compile-tokens.py" "$D41OPT/tokens.json" --out-css "$D41OPT/tokens.css"   --out-tailwind "$D41OPT/tokens.theme.css" --verify >/dev/null 2>&1   && rm -f "$D41OPT/tokens.css"   && ! python3 "$VD/compile-tokens.py" "$D41OPT/tokens.json" --out-css "$D41OPT/tokens.css"        --out-tailwind "$D41OPT/tokens.theme.css" --verify >/dev/null 2>&1   && ok "D.41: a project with no Tailwind bridge passes, a project with no CSS does not"   || bad "D.41 treats the optional bridge and the required CSS alike"
+
+# ...and --verify refuses to guess its own paths, which is how a reviewer got a
+# false 'missing' on the day D.41 shipped.
+python3 "$VD/compile-tokens.py" "$ROOT/skins/base-site/tokens.json" --verify >/dev/null 2>&1
+[ "$?" -eq 2 ] && ok "D.41: --verify against default paths is refused, not answered"   || bad "D.41 --verify still compares against whatever is in the working directory"
+
 # --- [Т-1] the declared dark ramp ----------------------------------------
 # The dark theme used to live in a comment ("87/60/38% over #121212") next to
 # sixteen literals nobody could check against it. Now the sentence is